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.