Comentarios en Dart

El lenguaje Dart admite un total de 3 tipos de comentarios: comentarios de una sola línea, comentarios multilínea y comentarios de documentación; el compilador ignora el texto común dentro de los comentarios, y solo los comentarios de documentación sirven para generar la documentación del código.

El propósito de los comentarios es facilitar que los desarrolladores consulten el código y entiendan sus funciones y utilidades. Además, permiten ocultar temporalmente fragmentos de código para depurar programas y detectar fallos.

Los comentarios de documentación permiten generar automáticamente una guía de ayuda del código mediante herramientas. Resultan útiles tanto para revisar las funciones del propio código como para que otros desarrolladores entiendan tu trabajo.

Si has aprendido otros lenguajes, comprenderás los comentarios rápidamente. Su sintaxis es muy similar a los lenguajes tipo C como C, C++, Java o C#.

1. Comentario de una línea //

1. Comienza con el símbolo //;
2. Todo el contenido desde // hasta el final de la línea es ignorado por el compilador de Dart;
3. Solo afecta a la línea actual, no admite varias líneas.

Ejemplo

void main() {
  // TODO: Refactorizar a clase fábrica abstracta de saludos de llamas
  print('¡Bienvenido a mi granja de llamas!');
}
Lenguaje del código: JavaScript (javascript)

2. Comentario multilínea /* */

1. Marcador de apertura /*, marcador de cierre */;
2. Todo lo que haya entre /* y */ es ignorado por el compilador (salvo los comentarios de documentación, ver más abajo);
3. Admite escritura anidada.

Ejemplo

void main() {
  /*
   * Criar llamas requiere mucho trabajo, se podría considerar criar gallinas.

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}Lenguaje del código: Dart (dart)

En el código anterior, todo el contenido entre las llaves está comentado, no se compila y el compilador lo ignora completamente.

3. Comentarios de documentación

Sirven para generar la documentación API oficial. Cuando otros desarrolladores usen tu librería, podrán consultar las descripciones de clases, interfaces de funciones, parámetros y demás indicaciones, como si fuera un manual de instrucciones.

1. Dos formatos de escritura

• Comentario de documentación en una línea: varias líneas consecutivas con ///, tiene el mismo efecto que el multilínea. Ten en cuenta que son tres barras inclinadas.
• Comentario de documentación multilínea: empieza con /** y termina con */. Fíjate en el asterisco extra al principio.

2. Reglas sintácticas fundamentales

1. El texto común dentro de un comentario de documentación es ignorado por el analizador de código;
2. Sintaxis especial: identificador entre corchetes [] para referirte a clases, métodos, campos, variables de nivel superior, funciones y parámetros;
3. Los nombres dentro de los corchetes se resuelven en el ámbito léxico del código comentado;
4. Tras generar la documentación, [identificador] se convierte automáticamente en un enlace hipervínculo hacia su documentación correspondiente.

Ejemplo

// Comentario simple de una línea: definición de la clase Alimento
class Food {
  String type;
  // Comentario de una línea: cantidad de fardos de alimento
  int baleCount;

  Food(this.type, this.baleCount);
}

/*
Comentario multilínea simple:
Enumeración de tipos de actividad para el método de ejercicio de llamas
Demostración de comentarios anidados
/* Comentario anidado interno */
*/
enum Activity {
  walk,
  run,
  graze
}

/// Mamífero camélido domesticado de Sudamérica (llama, nombre científico Lama glama)
///
/// Antes de la época de Colón, las civilizaciones andinas usaban las llamas para carne y transporte.
///
/// Al igual que otros animales, las llamas necesitan alimentarse: usa alimento de tipo [Food] y llama al método [feed].
class Llama {
  String? name;

  /// Alimenta a la llama con el alimento [food] indicado
  ///
  /// Una llama consume normalmente un fardo de heno por semana.
  void feed(Food food) {
    // Comentario de una línea: imprimir información de alimentación
    print("${name} ha comido ${food.baleCount} fardos de ${food.type}");
  }

  /// Hace que la llama realice la actividad [activity] durante [timeLimit] minutos
  void exercise(Activity activity, int timeLimit) {
    print("${name} realiza la actividad ${activity.name} durante ${timeLimit} minutos");
  }
}

void main() {
  // TODO: Ampliación para gestionar varias llamas en el futuro
  Llama larry = Llama();
  larry.name = "Larry";

  // Crear alimento de heno
  Food hay = Food("heno", 1);
  larry.feed(hay);

  // Paseo de 20 minutos para la llama
  larry.exercise(Activity.walk, 20);
}
Lenguaje del código: PHP (php)

Después de generar la documentación: [feed] enlaza con la documentación del método feed de la clase actual, [Food] enlaza con la documentación de la clase Food.

D:\dartdemo\firstdart>dart run
Building package executable...
Built firstdart:firstdart.
Larry ha comido 1 fardos de heno
Larry realiza la actividad walk durante 20 minutos

D:\dartdemo\firstdart>dart doc
Documenting firstdart...
Discovering libraries...
Linking elements...
Precaching local docs for 136851 elements...
Initialized dartdoc with 50 libraries
Generating docs for library firstdart.dart from package:firstdart/firstdart.dart...
Found 0 warnings and 0 errors.
Documented 1 public library in 10.3 seconds
Success! Docs generated into d:\dartdemo\firstdart\doc\apiLenguaje del código: JavaScript (javascript)

A continuación se crea una carpeta doc en el directorio del proyecto, al abrirla verás la documentación generada

Herramientas complementarias

1. Herramienta generadora de documentación: dart doc Función: analiza el código fuente Dart y genera automáticamente documentación API en formato HTML. La documentación oficial de Dart se crea con esta herramienta.
2. Referencia de normas de comentarios: Guía oficial «Effective Dart: Documentation», donde puedes consultar estructuras y estilos estándar para escribir comentarios.

Resumen

Tabla comparativa

Tipo de comentario	Símbolo inicial	Multilínea	Anidado	Propósito
Comentario una línea	//	No, solo una línea	No	Notas temporales, tareas pendientes (TODO)
Comentario multilínea común	/* */	Sí, varias líneas	Sí	Comentar bloques grandes de código, descripciones extensas
Comentario de documentación	/// / /** */	Sí	No recomendado	Redactar API de clases/métodos/variables, generar documentación oficial, enlaces a identificadores con []