Skip to content

Analyzer uses the doc comment of the first import/export/part as the library doc comment when there is no library directive #64700

Open

Description

@szakarias

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:

https://github.com/dart-lang/sdk/blob/main/pkg/analyzer/lib/src/summary2/informative_data.dart#L648

docComment: _getDocumentationComment(unit.directives.firstOrNull),

For example, in a file with no library directive:

/// Line 1
import 'dart:async';

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.

Activity

  1. added
    area-devexpFor issues related to the analysis server, IDE support, linter, `dart fix`, and diagnostic messages.
    on Oct 22, 2026
  2. added
    area-dart-modelFor issues related to conformance to the language spec in the parser, compilers or the CLI analyzer.
    and removed
    area-devexpFor issues related to the analysis server, IDE support, linter, `dart fix`, and diagnostic messages.
    on Nov 2, 2026
  3. johnniwinther commented on Nov 4, 2026

    @johnniwinther
    Member

    @bwilkerson @scheglov @srawlins Do you know what to motivation is for the current behavior?

  4. srawlins commented on Nov 4, 2026

    @srawlins
    Member

    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.

  5. scheglov commented on Nov 4, 2026

    @scheglov
    Contributor

    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).

  6. FMorschel commented on Nov 4, 2026

    @FMorschel
    Contributor

    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

  7. scheglov commented on Nov 4, 2026

    @scheglov
    Contributor

    I want to be wrong here!

  8. scheglov commented on Nov 4, 2026

    @scheglov
    Contributor

    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.

  9. self-assigned this
    on Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area-dart-modelFor issues related to conformance to the language spec in the parser, compilers or the CLI analyzer.model-dartdocIssues related to analyzer support for dartdoc

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions