Clean URLs

[sethladd]

Many have asked for "clean" URLs for Dart's docs.

See also https://github.com/dart-lang/dartdoc-viewer/issues/60

[sethladd]

Kathy, I know you have some thoughts here. Did you want to specify the URL structure for dartdoc ?

[kwalrath]

Sorry for the delay. I searched for my past thoughts about URLs, and found this:

https://code.google.com/p/dart/issues/detail?id=21475

To summarize, here are examples of what I wanted:

https://api.dartlang.org/dart:html https://api.dartlang.org/dart:html.Element https://api.dartlang.org/dev/dart:html

For links to individual APIs, it could be this:

https://api.dartlang.org/dart:html#document https://api.dartlang.org/dart:html.AbstractWorker#addEventListener https://api.dartlang.org/dart:core.List#List- https://api.dartlang.org/dart:core.List#List-filled https://api.dartlang.org/dart:core.Object#==

I'm not married to having ":" in the URLs. "-" or "_" would be OK instead.

[sethladd]

Thanks Kathy!

What is

/dart:core.List#List- ? What is the trailing dash?

Would you be OK with

/dart:html/Element ? Notice the slash

[sethladd]

cc @keertip

[kwalrath]

I don't remember why /dart:core.List#List- had the dash.

And yep, I'd be happy with /dart:html/Element.

[sethladd]

On a scale of one to ten (one being you're weeping and wearing a black veil, and ten being you're dancing in a field of daisies)...

/dart:html/element.html

[keertip]

Like the /dart:html/element.html. The link /dart:core.List#List- points to the constructor. Not sure why we need the trailing -. Would prefer not to have it.

[kwalrath]

/dart:html/element.html seems OK to me. I'd say it's a 7, compared to the 10 of /dart:html/Element.

If both /dart:html/element.html & /dart:html/Element.html would work, that'd be more like an 8 or 9. I hope there are no cases where changing only the capitalization would take you to different pages.

[sethladd]

we'll probably lower-case everything. we won't support case-insensitive URLs, as that requires a server and we're trying to avoid that.

[alan-knight]

For api.dartlang.org, would this always go to stable? How would you access bleeding edge or dev docs? For not api.dartlang.org, is it possible to access docs for different versions? Where does the package name go?

The trailing - on List- is to distinguish the unnamed constructor from the name of the class. And I guess for consistency. If the List constructor named filled is List-filled, then the unnamed constructor is just the empty string in that position. If unnamed constructors are already distinguished from classes by their position in the URL, then I think it should be ok.

The current dartdoc viewer allows links to parameters. e.g. https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart:core.List#id_List-filled,fill The comment for fill does refer to both parameters, and could quite reasonably refer to the generic type as well.

If you don't allow those, then there are a lot of references in method comments that won't point anywhere. If you do allow it, then you have to be careful about distinguishing things at different levels. So I think the full list is something like [package] [version] library class | variable | method class constructor | class method | class variable | top-level function parameter constructor parameter | class generic | method parameter

There were some tricky cases around this. Don't forget that library names are allowed to have dots in them, so you'd want to be able to distinguish a.b.c (library a, class b, field c) from a.b.c (library a.b, top-level field c) from a.b.c (library a.b.c), and so on.

There are a lot of links out there that point to old doc URL schemes, some of them very old. The current server supports three or four different variations. So if we don't have a server, we're going to have a lot of dead links in google. Also, if we lower-case everything and have easy to remember URLs, but no server, we're going to get a lot of 404's on http://api.dartlang.org/dart:core/List.html and the like.

Operator names require a little bit of care, but mostly just careful escaping. But that can make the URLs rather less clean, or at least difficult to type. e.g. https://api.dartlang.org/dart:core/int#+ ?

[kwalrath]

When we say "no server", we're talking about making it easier to check docs locally, correct? We can always publish the files somewhere that does have a server, in which case the server can do all kinds of forwards and redirects.

[seaneagan]

The path library has both a top-level context field and a Context class, so /path/context referring to the Context class would be confusing, and I guess the field would need to be referenced as /path#context.

[a14n]

Same comment for dart:core.deprecate and dart:core.Deprecated. The current doc uses dart:core#id_deprecated and dart:core.Deprecated.

[sethladd]

Looks like, so far:

• we'll keep case-sensitive names
• files will end in .html to make it easier to just "double click and open"
• "no server" means we won't require a server to open docs
• We're generating relative URLs for everything, so a server is free to put any URL prefix in front, and all the links in the docs will just work

More to come!

[sethladd]

I think we've delivered clean URLs. We can open individual issues as needed.