Referencias a comentarios de documentación

Los comentarios de documentación (doc comments) pueden contener referencias a varios identificadores. Se pueden referenciar elementos, como funciones y clases, envolviendo su nombre entre corchetes ([...]) en un comentario de documentación (un comentario que comienza con ///). Algunos ejemplos:

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

Estos comentarios de documentación contienen referencias a la clase String, el parámetro object y el constructor Future.value.

Hacer referencia a elementos de código con referencias a comentarios de documentación tiene varios beneficios:

Las referencias a comentarios de documentación habilitan varias características del IDE:

• Autocompletado de código El nombre de un elemento se puede autocompletar dentro de los corchetes.
• Refactorización de cambio de nombre Cuando se cambia el nombre de un elemento mediante un comando del IDE, este puede reescribir los usos de ese elemento, incluyendo las referencias en los comentarios de documentación.
• Buscar referencias Cuando un IDE enumera todas las "referencias" a un elemento, puede incluir las referencias en los comentarios de documentación.
• Ir a la definición Un IDE también puede proporcionar soporte para ir a la definición en la ubicación de una referencia a un comentario de documentación.

En la documentación de la API generada por dart doc, una referencia a un comentario de documentación se enlaza, si es posible, a la página de documentación del elemento que se está referenciando. Si el elemento no tiene una página de documentación (por ejemplo, un parámetro de función, un parámetro de tipo o una clase privada), no se crea ningún enlace.

La mayoría de los miembros de la biblioteca se pueden referenciar en un comentario de documentación, incluyendo clases, constantes, enums, extensiones nombradas, tipos de extensión, funciones, mixins y alias de tipo. Esto incluye todos los miembros de la biblioteca dentro del alcance, ya sea declarados localmente, importados o importados con un doc import. Los miembros de la biblioteca que se importan con un prefijo de importación se pueden referenciar con el prefijo. Por ejemplo:

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

La mayoría de los miembros de una clase, un enum, una extensión, un tipo de extensión y un mixin también se pueden referenciar. Una referencia a un miembro que no está al alcance debe estar calificada (con prefijo) con el nombre de su contenedor. Por ejemplo, el método estático wait de la clase Future se puede referenciar en un comentario de documentación con [Future.wait]. Esto también se aplica a los miembros de instancia; el método add y la propiedad length de la clase List se pueden referenciar con [List.add] y [List.length]. Cuando los miembros del contenedor están al alcance, como en el comentario de documentación de un método de instancia, se pueden referenciar sin el nombre del contenedor calificador:

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

Se puede hacer referencia a los constructores sin nombre utilizando el nombre new, de forma similar al tear-off de un constructor sin nombre. Por ejemplo, [DateTime.new] es una referencia al constructor DateTime sin nombre.

Se puede hacer referencia a los parámetros de una función y a los parámetros de un tipo de función en un comentario de documentación solo cuando están al alcance. Por lo tanto, solo se pueden referenciar dentro de un comentario de documentación en la función de dicho parámetro o en un alias de tipo para el tipo de función contenedor de dicho parámetro.

Se puede hacer referencia a los parámetros de tipo en un comentario de documentación solo cuando están al alcance. Por lo tanto, un parámetro de tipo de un método, función de nivel superior o alias de tipo solo puede ser referenciado dentro de un comentario de documentación sobre ese elemento, y un parámetro de tipo de una clase, enum, extensión, tipo de extensión y mixin solo se puede referenciar dentro de un comentario de documentación sobre ese elemento o sobre uno de sus miembros.

El comentario de documentación para un alias de tipo que tiene como alias una clase, enum, tipo de extensión o mixin no puede hacer referencia a ninguno de los miembros del tipo con alias como si estuvieran al alcance.

Dart admite una etiqueta de documentación @docImport, la cual permite referenciar elementos externos en los comentarios de documentación sin necesidad de importarlos realmente. Esta etiqueta se puede especificar en un comentario de documentación encima de una directiva library. Por ejemplo:

/// @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 {}

Los doc imports admiten los mismos estilos de URI que los regular Dart imports, incluyendo los esquemas dart: y package:, así como rutas relativas. Sin embargo, no se pueden diferir (deferred) ni configurar con as, show o hide.