Generated API reference points to invalid links for Flutter/Dart classes leading to 404s

[jenmerritt]

Steps to reproduce

The generated API reference for packages seems to have a number 404s referencing invalid pages for Flutter/Dart classes. This was picked up from a review of API ref for arcgis_maps but seems to apply to any generated API ref - here are a few examples from "Flutter Favorite" packages:

• https://pub.dev/documentation/path_provider/latest/path_provider/
  E.g. click on Future referenced from various functions
• https://pub.dev/documentation/provider/latest/provider/StreamProvider-class.html
  E.g. click on Stream referenced in the doc
• https://pub.dev/documentation/firebase_core/latest/firebase_core/Firebase-class.html
  E.g. click on Future referenced in the methods

This doesn't seem to affect all/most classes, but from our review it has at least affected references to Future, Stream, and Color.

References to Future go to https://api.flutter.dev/flutter/dart-core/Future-class.html instead of https://api.flutter.dev/flutter/dart-async/Future-class.html

References to Stream go to https://api.flutter.dev/flutter/dart-core/Stream-class.html instead of https://api.flutter.dev/flutter/dart-async/Stream-class.html

References to Color go to https://api.flutter.dev/flutter/painting/Color-class.html instead of https://api.flutter.dev/flutter/material/Colors-class.html

Has anyone else seen this? Is this likely a doc generator issue? Or anything configuration wise at the package level?

Expected results

All API references go to the correct, corresponding page.

Actual results

Some API references are hitting invalid pages / 404.

Code sample

Code sample

n/a - see link examples above

Screenshots or Video

Screenshots / Video demonstration

n/a

Logs

Logs

n/a

Flutter Doctor output

Doctor output

n/a

[tirth-patel-nc]

thanks for reporting this. I can confirm the presence of broken links in multiple packages on pub.dev, though I'm unsure whether the issue belongs in this repo or dartdoc or pub repository. It specific to certain classes as you've reported. labelling for team's attention.

[jenmerritt]

Great, thanks @tirth-patel-nc - yeah I wasn't sure which repo it would ultimately fall into either! 👍

[justinmc]

@sfshaza2 Any idea if these broken links are something that we can fix directly? Or maybe issues should be opened directly on the offending packages.

[PaulAllanSturm]

Quick and easy steps:
Run:

flutter create my_app --platforms=android

Open lib/main.dart in your favorite editor, add this doc comment on the MyApp declaration:

/// [Future]
class MyApp extends StatelessWidget {

Run:

dart doc
open doc/api/main/index.html

Click on the "Future" link
Fails! dart doc has created a link to Future supposedly in core, but it should be in async.

Expected:
https://api.flutter.dev/flutter/dart-async/Future-class.html
Actual:
https://api.flutter.dev/flutter/dart-core/Future-class.html

[PaulAllanSturm]

This is definitely a problem with dartdoc. In _scoreElementWithLibrary, "Future" has 2 candidate libraries: dart:async and dart:core. dart:core gets a big boost here:

    // Same idea as the above, for the Dart SDK.
    if (library.name == 'dart:core') {
      scoredCandidate._alterScore(0.9, _Reason.packageName);
    }

Because of that, dart:core gets selected as the appropriate library for "Future". That then gets used to generate the (broken) link.
Here's the place in the dartdoc source where this is happening: https://github.com/dart-lang/dartdoc/blob/f1fe17752b1193ad52d69271ceb686cc3e4712b0/lib/src/model/canonicalization.dart#L169

[PaulAllanSturm]

We could sprinkle @canonicalFor tags in the affected libraries. But that's not really sustainable long-term -- it's hard to say what symbols would need it and what wouldn't. E.g., Future would need it, but FutureOr doesn't. The other approach would be to adjust the heuristics that dartdoc uses to determine the canonical library.