You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Analyzer uses the doc comment of the first import/export/part as the library doc comment when there is no library directive #64700
The Dart documentation comment specification says a doc comment documents a library only when it is placed before a library directive (§3.1); any other placement "is not considered a doc comment, and hence should be ignored by documentation tools".
The analyzer instead sets LibraryElement.documentationComment from the doc comment preceding the first directive of any kind:
LibraryElement.documentationComment is "/// Line 1" instead of null.
Note that the dangling_library_doc_comments lint already flags this placement and asks users to add a library; directive if they intend to document the library.
I think users were putting a doc comment at the top of a file, above what was typically an import directive, because no one used library directives. After we added unnamed libraries, it became easier to document a library by writing a doc comment above library;. I believe we now have warnings or lint rules that report when a doc comment is "dangling" above an import or export directive.
Now that we have library; should we drop support for other locations of the library documentation?
I guess we could check what code uses.
But I suspect that using library; might be not universal yet (or ever).
If we have diagnostics for the other cases and with the new quick-fixes and completion already doing the correct thing, I have to disagree with you here
I checked what code actually uses. In the latest versions of 369 pub.dev packages (top 100 each by downloads, likes, and points, plus some recently updated or created, so this is not a random sample), lib/ has 10,030 libraries. 1,153 of them have a doc comment on a library directive, and 6 have one on a first import, export, or part directive. Those 6 are in 2 packages: package:file (5) and package:easy_localization (1). Flutter's packages/flutter/lib has 0 out of 679 libraries.
dartdoc already ignores these comments as of 9.1.0-wip, and @docImport in them already has no effect in the analyzer. The dangling_library_doc_comments lint is in package:lints/core.yaml, and has a fix that moves the comment to a library directive.
So I propose to change the analyzer to read LibraryElement.documentationComment only from the library directive. dartdoc can then remove its workaround, once it requires an analyzer with this change.
Activity
Only treat a doc comment as library documentation when it precedes a …
Only treat a doc comment as library documentation when it precedes a …
Only treat a doc comment as library documentation when it precedes a …
Only treat a doc comment as library documentation when it precedes a …
johnniwinther commentedon Nov 4, 2026
@bwilkerson @scheglov @srawlins Do you know what to motivation is for the current behavior?
srawlins commentedon Nov 4, 2026
I think users were putting a doc comment at the top of a file, above what was typically an import directive, because no one used library directives. After we added unnamed libraries, it became easier to document a library by writing a doc comment above
library;. I believe we now have warnings or lint rules that report when a doc comment is "dangling" above an import or export directive.scheglov commentedon Nov 4, 2026
Now that we have
library;should we drop support for other locations of the library documentation?I guess we could check what code uses.
But I suspect that using
library;might be not universal yet (or ever).FMorschel commentedon Nov 4, 2026
If we have diagnostics for the other cases and with the new quick-fixes and completion already doing the correct thing, I have to disagree with you here
scheglov commentedon Nov 4, 2026
I want to be wrong here!
scheglov commentedon Nov 4, 2026
I checked what code actually uses. In the latest versions of 369 pub.dev packages (top 100 each by downloads, likes, and points, plus some recently updated or created, so this is not a random sample),
lib/has 10,030 libraries. 1,153 of them have a doc comment on alibrarydirective, and 6 have one on a firstimport,export, orpartdirective. Those 6 are in 2 packages:package:file(5) andpackage:easy_localization(1). Flutter'spackages/flutter/libhas 0 out of 679 libraries.dartdoc already ignores these comments as of 9.1.0-wip, and
@docImportin them already has no effect in the analyzer. Thedangling_library_doc_commentslint is inpackage:lints/core.yaml, and has a fix that moves the comment to alibrarydirective.So I propose to change the analyzer to read
LibraryElement.documentationCommentonly from thelibrarydirective. dartdoc can then remove its workaround, once it requires an analyzer with this change.scheglov commentedon Nov 4, 2026
https://dart-review.googlesource.com/c/sdk/+/574020
Elements. Read library documentation only from the library directive.