Comentarios

Dart admite comentarios de una sola línea, comentarios de múltiples líneas y comentarios de documentación.

Un comentario de una sola línea comienza con //. Todo lo que esté entre // y el final de la línea es ignorado por el compilador de Dart.

void main() {
  // TODO: refactor into an AbstractLlamaGreetingFactory?
  print('Welcome to my Llama farm!');
}

Un comentario de múltiples líneas comienza con /* y termina con */. Todo lo que esté entre /* y */ es ignorado por el compilador de Dart (a menos que el comentario sea un comentario de documentación; consulta la siguiente sección). Los comentarios de múltiples líneas se pueden anidar.

void main() {
  /*
   * This is a lot of work. Consider raising chickens.
​
  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}

Los comentarios de documentación son comentarios de múltiples líneas o de una sola línea que comienzan con /// o /**. El uso de /// en líneas consecutivas tiene el mismo efecto que un comentario de doc de múltiples líneas.

Dentro de un comentario de documentación, el analyzer ignora todo el texto a menos que esté encerrado entre corchetes. Usando corchetes, puedes hacer referencia a clases, métodos, campos, variables de nivel superior, funciones y parámetros. Los nombres entre corchetes se resuelven en el alcance léxico del elemento del programa documentado.

Aquí tienes un ejemplo de comentarios de documentación con referencias a otras clases y argumentos:

/// A domesticated South American camelid (Lama glama).
///
/// Andean cultures have used llamas as meat and pack
/// animals since pre-Hispanic times.
///
/// Just like any other animal, llamas need to eat,
/// so don't forget to [feed] them some [Food].
class Llama {
  String? name;
​
  /// Feeds your llama [food].
  ///
  /// The typical llama eats one bale of hay per week.
  void feed(Food food) {
    // ...
  }
​
  /// Exercises your llama with an [activity] for
  /// [timeLimit] minutes.
  void exercise(Activity activity, int timeLimit) {
    // ...
  }
}

En la documentación generada de la clase, [feed] se convierte en un enlace a los documentos del método feed, y [Food] se convierte en un enlace a los documentos de la clase Food.

Para analizar el código de Dart y generar documentación HTML, puedes usar la herramienta de generación de documentación de Dart, dart doc. Para ver un ejemplo de documentación generada, consulta la documentación de la API de Dart. Para obtener consejos sobre cómo estructurar tus comentarios, consulta Effective Dart: Documentación.