Guía de documentación profesional con dart doc

dart doc es la herramienta oficial que transforma tus comentarios en una documentación técnica estructurada en formato HTML. A diferencia de los comentarios de implementación (//), los comentarios de documentación (///) están diseñados para ser parseados por el compilador y convertidos en una guía de uso con enlaces y formato. Esto es posible porque dart doc realiza un análisis estático del código, vinculando cada comentario con su declaración correspondiente mediante el árbol de sintaxis abstracta (AST). Debes usarla sistemáticamente cuando publiques un paquete en pub.dev o cuando desarrolles librerías para otros equipos, ya que la calidad de la documentación influye directamente en la puntuación de tus paquetes en el ecosistema. Si no sigues las convenciones de formato, especialmente en la estructura de los párrafos y las referencias, la navegación en la documentación se romperá y la ayuda contextual en el IDE (como el “hover” de información) será confusa o ilegible para otros desarrolladores.

import 'dart:async';

/// Representa el resultado final de un proceso de transformación.
class Resultado {
  /// El valor procesado y listo para su uso.
  final String valor;

  const Resultado(this.valor);

  @override
  String toString() => 'Resultado(valor: $valor)';
}

/// Excepción lanzada cuando la entrada de datos no es válida.
class ErrorDeEntrada extends Exception {
  @override
  String toString() => 'ErrorDeEntrada: La entrada está vacía o es inválida.';
}

/// Un motor encargado de transformar cadenas de texto.
///
/// Esta clase permite tomar un [String] y convertirlo en un objeto [Resultado].
/// Es ideal para flujos de procesamiento de texto asíncronos.
///
/// ### Ejemplo de uso:
/// 

dart
/// void main() async {
/// final motor = MotorTransformador();
/// try {
/// final res = await motor.transformar(‘hola mundo’);
/// print(res); // Resultado(valor: HOLA MUNDO)
/// } on ErrorDeEntrada {
/// print(‘Error: Entrada inválida’);
/// }
/// }
///

///
  /// Retorna un `Future` que se resuelve con el [Resultado] procesado.
class MotorTransformador {
  /// Transforma el texto recibido en un [Resultado] con el texto en mayúsculas.
  ///
  /// Si el parámetro `entrada` es una cadena vacía, se lanzará un [ErrorDeEntrada].
  ///
  /// Retorna un `Future` con el valor transformado.
  Future<Resultado> transformar(String entrada) async {
    // Simulamos una operación asíncrona para ilustrar el flujo
    await Future.delayed(const Duration(milliseconds: 100));

    if (entrada.isEmpty) {
      throw ErrorDeEntrada();
    }

    return Resultado(entrada.toUpperCase());
  }
}

void main() async {
  final motor = MotorTransformador();

  // Caso de éxito
  final res = await motor.transformar('dart documentation');
  print('Éxito: $res');

  // Caso de error
  try {
    await motor.transformar('');
  } catch (e) {
    print('Capturado error esperado: $e');
  }
}

En el código anterior, hemos aplicado diversas reglas que dart doc interpreta para generar el HTML final. La clase MotorTransformador utiliza /// para definir su comportamiento. Fíjate en la primera línea de cada comentario: “Un motor encargado de transformar cadenas de texto”. Esta es la línea de resumen, y es la que el IDE mostrará en la ventana emergente cuando pongas el cursor sobre la clase.

Para la navegación, hemos usado referencias entre corchetes como [Resultado] y [ErrorDeEntrada]. El motor de documentación no solo trata esto como texto, sino que busca esas clases en el proyecto para crear links cruzados automáticos. Si el usuario hace clic en [Resultado] en la documentación generada, saltará directamente a la definición de esa clase.

Para los bloques de código, hemos empleado el formato Markdown con triple comilla invertida (``dart), lo que permite que la documentación enpub.devmantenga el resaltado de sintaxis. Finalmente, hemos evitado el uso de etiquetas antiguas como@paramo@returns`; aunque son compatibles, la convención moderna en Dart es usar prosa natural para describir los parámetros y los retornos, lo que hace que la lectura sea mucho más fluida y menos parecida a un manual técnico rígido.

El directorio de salida por defecto de este proceso es doc/api/, que puedes generar ejecutando dart doc en tu terminal.

El error frecuente

Un error común es olvidar la primera línea de resumen o intentar que esa primera línea contenga párrafos complejos.

/// Este es un comentario muy largo que explica 
/// detalladamente cómo funciona toda la lógica
/// de la función y por qué es importante.
///
/// {@template}
/// Este comentario es útil pero la primera línea
/// será lo único que vea el desarrollador en el IDE.
/// {@/template}
void funcionLarga() {}

Cuando usas este patrón, el “hover” (la ayuda que aparece al pasar el mouse sobre la función) se vuelve ilegible porque el IDE intenta mostrar todo el bloque o se corta de forma abrupta. La primera línea debe ser siempre una descripción concisa de una sola oración.

N° 100