Initial documentation for doc comment references

src/content/tools/doc-comment-references.md

@@ -0,0 +1,88 @@
+---
+title: Documentation comment references
+short-title: Comment references
+description: Learn about doc comment references and their syntax.
+---
+
+Doc comments can contain references to various code elements. A library member
+or class member, etc. can be referenced by wrapping its name in square brackets
+(`[...]`) in a doc comment (a comment starting with `///`). Examples:
+
+```dart
+/// 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.
+
+## Features of references
+
+There are several benefits to referring to a code element in a doc comment as a
+doc comment reference:
+
+### Editor features
+
+Doc comment references enable several IDE features. An element's name can be
+code-completed within square brackets. When an element is renamed via an IDE
+command, it can rewrite uses of that element, including references in doc
+comments. When an IDE lists all "references" to an element, it can include
+references in doc comments. An IDE can also provide Go-to-definition support at
+the location of a doc comment reference.
+
+### API documentation
+
+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 variable, or a private class), then no link is created.
+
+## What can be referenced
+
+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, or imported. Library members which are imported with an import prefix
+can be referenced with the prefix. Examples:
+
+```dart
+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 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]`. In-scope members like these can even be referenced without the
+qualifying container name:
+
+```dart
+abstract class MyList<E> implements List<E> {
+  /// Refer to [add] and [contains], which is declared on [Iterable].
+  void myMethod() {}
+}
+```
+
+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 paramter'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 which aliases a class, enum, extension type,
+or mixin cannot reference any of the aliased type's members, if it has any, as
+if they were in scope.