Commentaires Dart

Le langage Dart prend en charge 3 types de commentaires au total : commentaires sur une seule ligne, commentaires multilignes, commentaires de documentation ; le compilateur ignore le texte ordinaire dans les commentaires, seul le commentaire de documentation permet de générer la documentation du code.

Les commentaires servent aux développeurs à comprendre facilement les fonctions et le rôle du code. Ils permettent aussi de masquer temporairement des portions de code pour déboguer et identifier des défauts.

Les commentaires de documentation permettent d’utiliser des outils pour générer une aide API complète du projet. Ils facilitent la lecture de votre code pour vous-même et pour les autres développeurs qui utilisent votre bibliothèque.

Si vous avez appris d’autres langages, vous comprendrez rapidement les commentaires Dart. La syntaxe est quasi identique aux langages de type C : C, C++, Java, C#…

1. Commentaire sur une seule ligne //

1. Débute par // ;
2. Tout ce qui se trouve entre // et la fin de la ligne est ignoré par le compilateur Dart ;
3. N’agit que sur la ligne en cours, impossible de couvrir plusieurs lignes.

Exemple

void main() {
  // TODO : Refactoriser en usine abstraite de salutations de lamas ?
  print('Bienvenue dans ma ferme de lamas !');
}
Langage du code : JavaScript (javascript)

2. Commentaire multiligne /* */

1. Marqueur de début /*, marqueur de fin */ ;
2. Tout contenu entre /* et */ est ignoré par le compilateur (hors commentaires de documentation, voir ci-dessous) ;
3. Prend en charge l’imbrication.

Exemple

void main() {
  /*
   * Élever des lamas demande beaucoup de travail, on peut envisager d’élever des poulets.

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}Langage du code : Dart (dart)

Dans l’exemple ci-dessus, tout le code entre les accolades est commenté, il n’est pas compilé et le compilateur l’ignore complètement.

3. Commentaires de documentation

Ils servent à générer la documentation API officielle. Quand un développeur utilise votre bibliothèque, il peut consulter les descriptions des classes, fonctions, paramètres comme un manuel d’utilisation.

1. Deux formats d’écriture

• Commentaire de documentation sur une ligne : plusieurs lignes consécutives avec ///, équivalent au commentaire multiligne de doc. Attention, trois barres obliques.
• Commentaire de documentation multiligne : débute par /**, se termine par */. Notez l’étoile supplémentaire au début.

2. Règles syntaxiques principales

1. Le texte ordinaire dans un commentaire de documentation est ignoré par l’analyseur de code ;
2. La syntaxe spéciale : identifiant entre crochets [] permet de référencer des classes, méthodes, champs, variables globales, fonctions et paramètres ;
3. Les noms entre crochets sont résolus dans la portée lexicale du code commenté ;
4. Après génération de la documentation, [identifiant] devient automatiquement un lien hypertexte vers la documentation correspondante.

Exemple

// Commentaire simple sur une ligne : définition de la classe Nourriture
class Food {
  String type;
  // Commentaire sur une ligne : quantité de bottes de fourrage
  int baleCount;

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

/*
Commentaire multiligne simple :
Énumération des types d’activités pour la méthode de mouvement des lamas
Démonstration de commentaires imbriqués
/* Commentaire imbriqué interne */
*/
enum Activity {
  walk,
  run,
  graze
}

/// Mammifère camelidé domestiqué d’Amérique du Sud (llama, nom scientifique Lama glama)
///
/// Avant Christophe Colomb, les civilisations andines utilisaient les lamas pour la viande et le transport.
///
/// Comme tout animal, le lama a besoin de nourriture : utilisez de la nourriture de type [Food] et appelez la méthode [feed].
class Llama {
  String? name;

  /// Donner à manger au lama avec la nourriture [food] spécifiée
  ///
  /// Un lama consomme généralement une botte de foin par semaine.
  void feed(Food food) {
    // Commentaire sur une ligne : affichage du repas
    print("${name} a mangé ${food.baleCount} bottes de ${food.type}");
  }

  /// Faire faire au lama l’activité [activity] pendant [timeLimit] minutes
  void exercise(Activity activity, int timeLimit) {
    print("${name} fait l’activité ${activity.name} pendant ${timeLimit} minutes");
  }
}

void main() {
  // TODO : étendre la gestion de plusieurs lamas par la suite
  Llama larry = Llama();
  larry.name = "Larry";

  // Créer une ration de foin
  Food hay = Food("foin", 1);
  larry.feed(hay);

  // Promenade de 20 minutes pour le lama
  larry.exercise(Activity.walk, 20);
}
Langage du code : PHP (php)

Après génération de la documentation : [feed] pointe vers la documentation de la méthode feed de la classe, [Food] pointe vers la documentation de la classe Food.

D:\dartdemo\firstdart>dart run
Building package executable...
Built firstdart:firstdart.
Larry a mangé 1 bottes de foin
Larry fait l’activité walk pendant 20 minutes

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\apiLangage du code : JavaScript (javascript)

Un dossier doc est créé à la racine du projet ; en l’ouvrant vous trouverez la documentation générée

Outils associés

1. Outil de génération de documentation : dart doc Rôle : analyser le code source Dart et produire automatiquement une documentation API au format HTML. La documentation officielle de Dart est générée avec cet outil.
2. Référence sur les normes de commentaires : guide officiel 《Effective Dart: Documentation》, qui détaille la structure et le style standard des commentaires.

Synthèse

Tableau comparatif

Type de commentaire	Symbole de début	Multi-lignes	Imbrication autorisée	Usage
Commentaire simple ligne	//	Non, une seule ligne	Non	Notes temporaires, tâches à faire (TODO)
Commentaire multiligne classique	/* */	Oui, plusieurs lignes	Oui	Masquer de grands blocs de code, longues explications
Commentaire de documentation	/// / /** */	Oui	Déconseillé	Rédiger l’API des classes/méthodes/variables, générer la doc officielle, liens via [] sur les identifiants