`comentarii și documentare` în Dart

Biblioteci, importuri și comentarii Dart 1.0

Textul ignorat de compilator: // pe un rând, /* */ pe mai multe, și /// pentru documentația generată cu dart doc.

Sintaxă

// comentariu pe un rând
/* comentariu
   pe mai multe rânduri */
/// comentariu de documentare (pentru dart doc)
/// Folosește [NumeClasa] sau [parametru] pentru legături.

Ce face `comentarii și documentare`

// transformă în comentariu restul rândului, iar /* ... */ tot ce este între ele, chiar pe mai multe rânduri (și se pot imbrica). Comentariile explică de ce face codul ceva; ce face, ar trebui să se vadă din nume clare.

Comentariile de documentare încep cu /// și se pun deasupra claselor, funcțiilor și câmpurilor publice. Editorul le arată când treci cu mouse-ul peste nume, iar dart doc generează din ele un site HTML. În ele poți folosi Markdown și referințe între paranteze drepte: [Elev], [nota].

Prima propoziție a unui comentariu /// trebuie să fie un rezumat scurt; detaliile vin după un rând gol. Comentarii speciale ca // ignore: nume_regula îi spun analizorului să nu raporteze o problemă anume pe rândul următor.

Exemple

Exemplul 1: Cele trei feluri de comentarii

Comentariile nu schimbă rezultatul; codul din /* */ nu se execută.

/// Calculează prețul final după aplicarea reducerii.
///
/// [procent] trebuie să fie între 0 și 100.
double pretRedus(double pret, int procent) {
  // Rotunjim la 2 zecimale, ca pe bonul fiscal.
  return (pret * (100 - procent) / 100 * 100).round() / 100;
}

void main() {
  print(pretRedus(199.99, 15)); // reducere de Black Friday
  /* Varianta veche, păstrată pentru comparație:
  print(199.99 - 30);
  */
  print(pretRedus(49.5, 0));
}

Rezultat

169.99
49.5

Exemplul 2: Documentarea unei clase

Așa arată o clasă documentată pentru dart doc. Referințele [Elev] și [adaugaNota] devin legături în documentația generată.

/// Un elev dintr-un catalog școlar.
///
/// Exemplu:
/// ```dart
/// final ana = Elev('Ana')..adaugaNota(10);
/// ```
class Elev {
  /// Numele complet al elevului.
  final String nume;

  final List<int> _note = [];

  /// Creează un [Elev] fără note.
  Elev(this.nume);

  /// Adaugă o notă între 1 și 10. Vezi și [media].
  void adaugaNota(int nota) => _note.add(nota);

  /// Media notelor adăugate cu [adaugaNota], sau 0 dacă nu există note.
  double get media => _note.isEmpty ? 0 : _note.reduce((a, b) => a + b) / _note.length;
}

void main() {
  final ana = Elev('Ana')
    ..adaugaNota(10)
    ..adaugaNota(9);
  print('${ana.nume}: ${ana.media}');
}

Rezultat

Ana: 9.5

Exemplul 3: Generarea documentației

Într-un proiect creat cu dart create, dart doc scrie site-ul în doc/api/.

dart doc
open doc/api/index.html

Rezultat în terminal

Generating docs for library magazin.dart from package:magazin/magazin.dart...
Found 0 warnings and 0 errors.
Documented 1 public library in 1.8 seconds
Success! Docs generated into /Users/ana/proiecte/magazin/doc/api

Greșeli frecvente

/** ... */ pentru documentare: funcționează, dar stilul Dart recomandă ///.
Comentarii care repetă codul (i++; // crește i): nu ajută. Explică motivul, nu acțiunea.
Cod vechi lăsat comentat la nesfârșit: îl găsești oricând în istoricul Git, șterge-l.

Comenzi înrudite

library: Directiva de la începutul unui fișier Dart care marchează biblioteca, pentru documentație sau adnotări.
dart analyze: Verifică codul fără să-l ruleze și raportează erori, avertismente și sfaturi de stil (infos).
string interpolation: Introduce valori în texte cu $variabila sau ${expresie}, fără concatenare cu +.

Ce face comentarii și documentare