dartdoc comment references

Dartdoc comment references

A "comment reference" in dartdoc is an expression wrapped by brackets within a documentation comment. They have a syntax similar to Dart expressions and are interpreted by dartdoc to create links to different parts of the documentation. The behavior is largely unspecified in the Dart language and so, this document describes Dartdoc's interpretation.

Syntax

The syntax of a documentation comment often looks like a simplified version of a Dart expression. Dartdoc's grammar for them is as follows:

<rawCommentReference> ::= <prefix>?<commentReference><suffix>?

<prefix> ::= <constructorPrefixHint>
  | <leadingJunk>

<suffix> ::= <callablePostfixHint>
  | <trailingJunk>

<leadingJunk> ::= ('const' | 'final' | 'var')(<whitespace>+)

<trailingJunk> ::= '('<notClosedParenthesis>*')'
  | '<'<notGreaterThan>*'>'
  | '?'
  | '!'
  | <whitespace>*

<constructorPrefixHint> ::= 'new '

<callablePostfixHint> ::= '()'

<commentReference> ::= (<globalScopeReference> '.')? <dartdocIdentifier> ('.' <dartdocIdentifier>)*

<globalScopeReference> ::= <packageName> '.' <libraryName>
  | <libraryName>

<dartdocIdentifier> ::= <dartIdentifier>
  | ('operator' <whitespace>*)?<operator>

A rawCommentReference includes all text between the two brackets, passed into dartdoc via the Markdown parser which interprets documentation comments generally.

The prefix and suffix include extra, optional characters that are allowed to either make the documentation comment more readable in prose, or to pass information to Dartdoc on what kind of identifier should be resolved.

The constructorPrefix, if present, signals to Dartdoc that we should resolve the comment reference exclusively to a constructor, to disambiguate a reference from a type of the same name.

The callableSuffix, if present, signals to Dartdoc to resolve the comment reference to callable items, including constructors. This can be used to disambiguate constructors, or simply to restrict resolution to a function or method.

leadingJunk and trailingJunk are accepted by the parser, but ignored, if present.

The commentReference isolated from the prefix/suffix, consists of a period-separated list of dartdoc identifiers. It can optionally include globalScopeReference, with a package name and library name, or just a library name, to further specify what the reference refers to. Some examples: foo, ClassName.foo, libName.ClassName.foo, and even packageName.libName.ClassName.foo.

libraryName is the name of the library a symbol is defined in or exposed in via reexporting. Because library names can contain periods, using them can create ambiguity in parsing, with multiple possible parses for a single commentReference. See below for how this is handled.

packageName is the name of a Dart "package", which can be the Dart SDK, a pub or pub-like package defined by a pubspec.yaml file, or another package type if dartdoc is extended to support it. Like libraryName, this can create ambiguities in parsing. See below for how this is handled.

A dartdocIdentifier is different from a dart identifier in that it can include the word operator, some intervening whitespace, and a Dart operator, itself.

Basic syntax

Member variables

Parameters and Type Parameters

Callables

Constructors

Ambiguous Syntax

Evaluation

Simple evaluation

Borrowing documentation via superchains

Exports, reexports, and scope

Caveats

Ambiguous Evaluation

Disambiguation Rules

Resolving errors

Unresolved doc references

Examples

• Default constructor: [MyClass.MyClass]
• Named constructors: [MyClass.namedConstructor]

From a class with a conflicting member name, the top-level variable of the same name in that library:

library myLib;
final String myString = "hi";

class A {
  final String myString = "there";

  /// The lovely [A] class's [foo] method.
  /// [myString] - refers to A.myString
  /// [myLib.myString] - refers to the top level myString
  void foo() {}
}