Documentation comment references

Doc comments can contain references to various identifiers. Elements, such as functions and classes, can be referenced by wrapping their name in square brackets ([...]) in a doc comment (a comment starting with ///). Some examples:

/// Returns a [String].
String f() => 'Hello';
​
/// Wraps [object] with [Future.value].
Future<T> g<T>(T object) => Future.value(object);

These doc comments contain references to the String class, the object parameter, and the Future.value constructor.

There are several benefits to referring to code elements with doc comment references:

Doc comment references enable several IDE features:

• Code completion An element's name can be code-completed within square brackets.
• Rename refactoring When an element is renamed via an IDE command, the IDE can rewrite uses of that element, including references in doc comments.
• Find references When an IDE lists all "references" to an element, it can include references in doc comments.
• Go to definition An IDE can also provide Go-to-definition support at the location of a doc comment reference.

In API documentation generated by dart doc, a doc comment reference is linked, if possible, to the documentation page of the element being referenced. If the element does not have a documentation page (for example, a function parameter, a type parameter, or a private class), then no link is created.

Most library members can be referenced in a doc comment, including classes, constants, enums, named extensions, extension types, functions, mixins, and type aliases. This includes all in-scope library members, either declared locally, imported, or imported with a doc import. Library members that are imported with an import prefix can be referenced with the prefix. For example:

import 'dart:math' as math;
​
/// [List] is in scope.
/// So is [math.max].
int x = 7;

Most members of a class, an enum, an extension, an extension type, and a mixin can also be referenced. A reference to a member that is not in scope must be qualified (prefixed) with its container's name. For example, the wait static method on the Future class can be referenced in a doc comment with [Future.wait]. This is true for instance members as well; the add method and the length property on the List class can be referenced with [List.add] and [List.length]. When container members are in-scope, such as in an instance method's doc comment, they can be referenced without the qualifying container name:

abstract class MyList<E> implements List<E> {
  /// Refer to [add] and [contains], which is declared on [Iterable].
  void myMethod() {}
}

Unnamed constructors can be referenced by using the new name, similar to the tear-off of an unnamed constructor. For example, [DateTime.new] is a reference to the unnamed DateTime constructor.

Parameters of a function and parameters of a function type can be referenced in a doc comment only when they are in scope. They can therefore only be referenced within a doc comment on such a parameter's function or on a type alias for such a parameter's enclosing function type.

Type parameters can be referenced in a doc comment only when they are in scope. Therefore, a type parameter of a method, top-level function, or type alias can only be referenced within a doc comment on that element, and a type parameter of a class, enum, extension, extension type, and mixin can only be referenced within a doc comment on that element or on one of its members.

The doc comment for a type alias that aliases a class, enum, extension type, or mixin can't reference any of the aliased type's members as if they were in scope.

Dart supports a @docImport documentation tag, which enables external elements to be referenced in documentation comments without actually importing them. This tag can be specified in a doc comment above a library directive. For example:

/// @docImport 'dart:async';
library;
​
/// Doc comments can now reference elements like
/// [Future] and [Future.value] from `dart:async`,
/// even if the library is not imported with an actual import.
class Foo {}

Doc imports support the same URI styles as regular Dart imports, including the dart: and package: schemes as well as relative paths. However, they can't be deferred or configured with as, show, or hide.