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

extension type sidebar has a href bug after being loaded in the browser #3663

Open isoos opened 8 months ago

isoos commented 8 months ago

Case 1: SDK API docs

  1. Visit: https://api.dart.dev/stable/3.3.0/dart-js_interop/JSObject/JSObject.html
  2. Hover over the left-side JSObject under constructors. It will link to https://api.dart.dev/stable/dart-js_interop/JSObject/JSObject.html
  3. Notice that there is no 3.3.0 in the linked URL. However, if you click on it, api.dart.dev redirects you again to the URL in the first point.

Also visible via curl -v:

 location: https://api.dart.dev/stable/3.3.0/dart-js_interop/JSObject/JSObject.html

Case 2: pub.dev docs:

  1. Visit https://pub.dev/documentation/web/latest/web/HTMLTimeElement/HTMLTimeElement.html
  2. Hover over the HTMLTimeElement constructor on the left side. The link is the following:
https://pub.dev/documentation/web/web/HTMLTimeElement/HTMLTimeElement.html - link
https://pub.dev/documentation/web/latest/web/HTMLTimeElement/HTMLTimeElement.html - original

You can see that the /latest/ segment got "swallowed" by the linking. The root cause can be seen in the next case:

Case 3: local reproduction:

with a minimal pubspec and a very simple library:

extension type IdNumber(int id) {
  // Wraps the 'int' type's '<' operator:
  operator <(IdNumber other) => id < other.id;
}

class Options {
  Options();
}

Observe the generated files:

  doc/api/x/Options-class-sidebar.html:
 <li><a href="x/Options/Options.html">Options</a></li>

  doc/api/x/IdNumber-extension-type-sidebar.html
 <li><a href="../x/IdNumber/IdNumber.html">IdNumber</a></li>

While the regular class relative linking starts with the library folder, the extension type's start with one directory up. I think the fix should be to start with the same way as the regular class does.

Notes

Local testing with a simple HTTP server works, because ../../../../../ won't cause an issue, it will resolve to the root, regardless of the levels going up.

isoos commented 8 months ago

/cc @parlough @srawlins