flutter docs are missing lots of classes

[devoncarew]

The 0.9.7+2 release introduced an issue where the generated docs for flutter are missing many classes.

This page: https://docs.flutter.io/flutter/material/material-library.html

only shows ~5 classes.

[devoncarew]

flutter/flutter#5644

[sethladd]

Is this still the case?

[Hixie]

Moving to P0 because if this isn't fixed then it's going to block deployment of subsequent fixes.

[eseidelGoogle]

Correct, we're intentionally pinned on an older version of dartdoc due to this regression:
https://github.com/flutter/flutter/blob/master/dev/bots/docs.sh#L5

[astashov]

It seems like the bug is in analyzer. It got broken at this commit, when the analyzer version was bumped to ^0.28.1 (and it's still broken with 0.29.1). If I just change the analyzer version back to 0.27 at that commit and nothing else, it works just fine and generates all the classes successfully.

It seems like that happens because by some reason analyzer doesn't gather exported namespaces correctly. E.g., there:

dartdoc/lib/src/model.dart

Line 973 in 648ad06

_exportedNamespace =

, analyzer 0.27 returns the namespace instance with like 600+ records inside, and analyzer 0.28 returns the namespace with just ~10 records.

@devoncarew do you want me to dig it deeper, or you will pass this to the analyzer team?

[keertip]

@bwilkerson , should dartdoc be doing something else instead of

_exportedNamespace =
        new NamespaceBuilder().createExportNamespaceForLibrary(element);

to get all the public elements for a library? Has this api changed?

[bwilkerson]

No, the API hasn't changed, and the code hasn't changed since 6/16, and most of it has been stable since 4/16. I don't see any obvious cause for the issue. I'll need to get a reproduction case so that I can step through the creation of the namespace.

[keertip]

@astashov , how did you run dartdoc on flutter?

[eseidelGoogle]

https://github.com/flutter/flutter/blob/master/dev/bots/docs.sh will generate all of Flutter's docs. You'll note that it intentionally pins us to an old version of dartdoc to avoid this bug.

Travis does our doc generation on every commit. https://github.com/flutter/flutter/blob/master/.travis.yml is its config. Just two scripts it runs. :)

[astashov]

To use a debugger, I run it somewhat like this:

git clone https://github.com/flutter/flutter.git ~/projects/flutter
cd ~/projects/flutter
bin/flutter update-packages
git clone https://github.com/dart-lang/dartdoc.git ~/projects/dartdoc
cd ~/projects/dartdoc
pub get

DART_SDK=~/projects/flutter/bin/cache/dart-sdk FLUTTER_ROOT=~/projects/flutter bin/dartdoc.dart \
  --header ~/projects/flutter/dev/docs/styles.html \
  --header ~/projects/flutter/dev/docs/analytics.html \
  --exclude temp_doc \
  --favicon=~/projects/flutter/dev/docs/favicon.ico \
  --use-categories \
  --include-external animation \
  --include-external cassowary \
  --include-external foundation  \
  --include-external gestures \
  --include-external http \
  --include-external material \
  --include-external painting \
  --include-external physics \
  --include-external rendering \
  --include-external scheduler \
  --include-external services \
  --include-external widgets \
  --include-external driver_extension \
  --include-external flutter_driver \
  --include-external flutter_markdown \
  --include-external flutter_markdown_raw \
  --include-external flutter_test \
  --input ~/projects/flutter/dev/docs \
  --output ~/projects/flutter/dev/docs/doc/api

I can try to provide SSCCE for it, if you want.

[keertip]

Found the problem - dartdoc is picking up the wrong library named material. It is generating docs for flutter/lib/src/material/material.dart instead of flutter/lib/material.dart. Working on making the --include-external flag more strict. Once that is in place, can tweak the flutter docs script to pass in more unambiguous names for the libraries.

[eseidelGoogle]

Fantastic! Thank you both!

[astashov]

@keertip woohoo, great job! I'll move on to #1153 then :)

[eseidelGoogle]

Should library name collisions have caused (or cause in the future) some sort of warning inside dartdoc or the analyzer? We're happy to update names and/or be more specific for flags like --include-external as necessary in Flutter.

[sethladd]

Yay! And printing out a warning sounds like a good idea.

…

On Tue, Dec 13, 2016, 8:16 PM Eric Seidel ***@***.***> wrote: Should library name collisions have caused (or cause in the future) some sort of warning inside dartdoc or the analyzer? We're happy to update names and/or be more specific for flags like --include-external as necessary in Flutter. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1236 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAVZ2dbWXMXny1jps2B4M3TryQpL6pdks5rH22MgaJpZM4JvyRh> .

[sethladd]

Thanks @keertip ! Do we need to do anything on the Flutter side?

[eseidelGoogle]

Now that @keertip and @astashov did the hard work of figuring out what was wrong. :) I decided to slap together an alternative fix which includes the warnings I had imagined:
https://github.com/eseidelGoogle/dartdoc/tree/external_warnings

If that's useful to either @devoncarew or @keertip, please feel free to take it! (Note that in that commit it's using the old match function instead of @keertip's new one, the new one is included commented out.)

Note that running with that patch I immediately see more potential problems with the current system (even after the fix):

ERROR: animation matches multiple libraries: (/src/flutter/packages/flutter/lib/animation.dart, /src/flutter/packages/flutter/lib/src/animation/animation.dart)
ERROR: http matches multiple libraries: (/src/flutter/packages/flutter/lib/src/http/http.dart, /src/flutter/packages/flutter/lib/http.dart)
ERROR: material matches multiple libraries: (/src/flutter/packages/flutter/lib/src/material/material.dart, /src/flutter/packages/flutter/lib/material.dart)
WARNING: driver_extension matches no libraries.

[devoncarew]

Thanks Eric! The additional checks make sense; better to fast-fail here if there's ambiguity about the library to gen docs for.