search

dart-lang / dartdoc

API documentation tool for Dart.
https://pub.dev/packages/dartdoc
BSD 3-Clause "New" or "Revised" License
473 stars 119 forks source link

Add redirection stubs for non-canonical identifiers #1371

Open jcollins-g opened 7 years ago

jcollins-g commented 7 years ago

Canonicalization greatly shrinks the number of generated docs, but is much less forgiving for links to elements in the now 'wrong' place. It seems to be the right thing to do to leave behind stubs that browser-redirect to the right place so that old links can continue to work for newly generated docs, and any bugs in canonicalization, when fixed, don't have a cascade impact on users.

jcollins-g commented 6 years ago

I misprioritized this: there are no broken links or major navigational hurdles. Instead, this should be an enhancement.

jcollins-g commented 4 years ago

I think this could actually be important. If redirection stubs existed, dartdoc wouldn't have to be absolutely sure of canonicalization for non-documented packages. This means that it wouldn't have to analyze and build full data structures for every file in every dependent package just in case it contained a canonical reexport of something -- which would greatly speed up dartdoc's initialization time.

This requires further thought in case there are edge cases I'm not recognizing.