Make version-agnostic links the default

[kwalrath]

People are constantly linking to, say, https://api.dartlang.org/1.12.1/dart-core/Object-class.html when they should instead be linking to https://api.dartlang.org/stable/dart-core/Object-class.html.

We should make it easier to get a good permalink. This could be combined, somehow, with showing the current version and a way of switching to the stable/dev version of the docs.

Personally, I'd rather have the displayed URL be generic (https://api.dartlang.org/dart-core/Object-class.html) unless you choose a particular version.

An (extreme) example of this is in the AngularJS docs:

The docs for angular.bind are in https://docs.angularjs.org/api/ng/function/angular.bind. A dropdown at the upper left shows which build the docs reflect. If you want another build, you can choose it from the dropdown. For example, if you use v1.4.8, then the URL switches to https://code.angularjs.org/1.4.8/docs/api/ng/function/angular.bind. (It's difficult to get back to the real "latest", so ... not a perfect solution.)

To repeat: We should make it easy for people to do the right thing, which I believe is linking to the latest stable version of the docs. We should make it possible to link to other docs, with minimal effort on the linker's part.

[sethladd]

Good feedback, but not really an issue with dartdoc. This is an issue with hosting the docs.

The doc generation doesn't assume or specify a specific version in the URL path. It just starts with library-name and goes from there.

Angular docs are free to experiment with new ways to create URL paths, for sure!

Going to close, but only because angular can and should change the URL structure without needing anything from dartdoc.

[kwalrath]

Where should I file bugs about dartdocs.org? (I'm talking about that, not the angular docs.)

Also, is it easy to implement this change without support from dartdoc?

[sethladd]

You probably don't need anything from dartdoc. As for dartdocs.org, try this repo: https://github.com/astashov/dartdocs.org/issues

[kwalrath]

Sorry, I meant api.dartlang.org, not dartdocs.org.

[sethladd]

Ah. Then you want this: https://github.com/dart-lang/api.dartlang.org/issues

[kwalrath]

Thanks, I've added an issue there.