Need ability to create library-level API docs without an explicit library tag.

[Sfshaza]

Bob suggests:

• If there is a doc before any declarations in the library
• and the doc comment is not directly (i.e. without a blank line) before the first declaration.

Then we treat that as the doc comment for the library.

[keertip]

dartdoc gets the doc comment for all elements from the analyzer. So analyzer would need to be modified to support getting doc comments from a dart file before the first declaration.

@Sfshaza, could you open a issue for the analyzer and link it in here? Thanks!

[Sfshaza]

https://github.com/dart-lang/analyzer_cli/issues/81

[munificent]

After some discussion, the new proposed rule is simpler:

Use the first doc comment attached to any directive (import, export, etc.).

[keertip]

This fix has been made to the analyzer. Upgrading to new analyzer package, current 0.27.1+2, will fix this issue.

[devoncarew]

I think this is fixed?

[kwalrath]

I don't know if it was ever fixed.

I don't see any library comments for the stagehand docs unless I add a library statement (library stagehand;) above the imports. We removed the library statement in dart-archive/stagehand#307 (3/2016), v1.0.2, and that's when the library comments disappeared from the dartdoc: 1.0.2 library docs, 1.0.1 library docs

[jcollins-g]

You're right, we still require the library statement -- if it was fixed at one point, it was before I took over.

[jcollins-g]

And I'm actually not right at all. This does work in dartdoc's internal tests to my surprise. Don't know why it doesn't work in your case, will require some investigation.