☂️ Documentation imports

[srawlins]

The original issue describing a new "documentation import" system is #50702, but it is a bit outdated, and has grown to be a pretty long issue. This issue serves as the new umbrella issue for the "documentation imports" feature.

BACKGROUND

Glossary

• Doc comment (or dartdoc comment or documentation comment) - a Dart code comment in which each line starts with three slashes (///), and which is placed just before a library element (class, top-level function, top-level constant, etc.) or a class/mixin/enum/extension element (method, field, etc.). A doc comment is parsed (by various tools) as Markdown text.
• Doc comment reference - the name of any element wrapped in square brackets, inside a doc comment. This is typically one identifier or two separated by a period, like [List] or [Future.wait].

OVERVIEW

The basic design is to add a dartdoc-style doc comment directive, called a "doc-import" which looks similar to an import directive. When a library directive has a documentation comment with doc-imports, the analyzer will add another layer of resolution scope, used when resolving doc comment references. Quick examples:

/// @docImport 'dart:async';
/// @docImport 'package:flutter/element.dart' show Element;
/// @docImport '../path/to/somwhere.dart';
/// @docImport 'dart:html' as 'html';
library;

/// We can now reference [Future] from dart:async, [Element] from Flutter's element library,
/// and [html.Element] from dart:html, even if none of these libraries are actually imported
/// by this library.
class Foo {}

DETAILED DESIGN/DISCUSSION

This feature is designed to be used only by static analysis tools like the Dart analyzer and dartdoc.

At the start of any line in a documentation comment on a library's library directive, a doc-import can be written. A doc-import looks exactly like a Dart import directive, with 3 differences:

• The first keyword is @docImport instead of import.
• The deferred keyword is not supported.
• Import configurations are not supported.

Otherwise, all other features of Dart imports are supported, including package URIs, relative file URIs, prefixes with "as", and "show" and "hide" combinators.

Each identifier in a library (both in code and in doc comment references) is resolved according to various scoping rules, which may resolve to a non-top-level identifier, or a top-level identifier from one of the top-level namespaces. (This is a simplification since a prefix itself is an identifier which needs resolution, and which can also be shadowed by a non-top-level identifier.) The presence of one-or-more doc-imports introduces a new scope, applicable only within doc comments. This doc-imports scope introduces visible names using the same rules and mechanisms as Dart imports.

New static warnings are reported in the following situations:

• when the URI cannot be resolved, according to the URI-resolving rules
• when elements from a doc import have name conflicts with each other, or elements from imports with the same prefix
• when a prefix name does not match certain identifier rules
• when a show or hide clause includes names of elements which are not found in the library's export namespace.
• when a doc import is redundant, duplicate, or unnecessary (various subtle definitions) with a regular import or another doc import (lower priority)
• when a doc import is unused (lower priority)
• when an element in a show or hide clause of a doc import is unused (lower priority)

TESTING PLAN

Support for this syntax will be tested in:

• analyzer's unit tests
• analysis server’s navigation tests, hover tests, etc.
• dartdoc’s reference unit tests

DOCUMENTATION PLAN

The support for this feature can be documented in an article on dart.dev.

This addresses #44637.

[FMorschel]

I think we can use this issue to track it all so:

• Make comment_references fixes add doc imports instead of normal imports #59759
• New lint for doc imports #59741
• Expand doc comment reference page with doc imports site-www#6140
• Dart doc shows no result in auto complete for type names and only for static declarations inside them #59724 (talks that auto-complete here should use doc-imports)
• Document @docImport in README.md dartdoc#3935
• @docImports should support as imports #56527
• Add a warning similar to UNUSED_IMPORT for doc imports that are unused. #55414

Not sure if you know of any other issues that are relevant to add here @srawlins