Skip to content

Resolve comment references with the analyzer and retire the universal scope #4283

Open

Description

@szakarias

Dartdoc resolves comment references with its own algorithm. When the analyzer cannot resolve a reference, dartdoc falls back to searching its universal reference scope, which holds every public element, library and package dartdoc has loaded, and which is populated by crawling packages beyond the ones being documented.

Inherited documentation is handled separately, by copying the parent's comment and re-resolving its references in the inheriting class.

We want to move both to the analyzer: references should be resolved from the analyzer's element, and inherited comments should be resolved where they were written rather than where they are displayed. URLs will be built from the resolved element rather than from an internal lookup.

This will be a breaking change. References that resolve only through the fallback will stop resolving; these are reported by the analyzer's comment_references lint and most are fixed by adding a missing @docImport.

However, not everything is fixed by a @docImport. Some references will resolve to a different element under the analyzer's scoping rules (#3762), and some forms have no lexical equivalent at all — for instance a library referred to by its bare name, such as [widgets], resolves today only because every public library is registered in the universal reference scope by name, and it cannot be expressed with @docImport as it currently works (dart-lang/sdk#56528). We will work through the remaining categories as we get to them.

Related: #4083 and #4224

Metadata

Metadata

Assignees

Labels

type-bugIncorrect behavior (everything from a crash to more subtle misbehavior)type-enhancementA request for a change that isn't a bug

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions