Documenting your programs

Documenting an application is of utmost importance in software engineering and Dart makes this very easy. The single-line (//) and multiline comments (/* */) are useful (for example, to comment out code or mark lines with // TODO), and they have counterparts /// and /** */ called documentation comments. In these comments (to be placed on the previous line), you can include references to all kinds of objects in your code (classes, methods, fields, and so on) and the Dartdoc tool (in Dart Editor, go to Tools | Generate Dartdoc) will generate an HTML documentation, where these references become links. To demonstrate, we will add docs to our banking example (refer to banking_v2doc.dart):

/**
 * A bank account has an [owner], is identified by a [number]
 * and has an amount of money called [balance].
 * The balance is changed through methods [deposit] and [withdraw].
 */
class BankAccount {
  String owner, number;
  double balance;
  DateTime dateCreated, dateModified;

  BankAccount(this.owner, this.number, this.balance)  {
    dateCreated = new DateTime.now();
  }

 /// An amount of money is added to the balance.
  deposit(double amount) {
    
  }

 /// An amount of money is subtracted from the balance.
  withdraw(double amount) {
    
  }
}

This results in the following documentation while viewing banking_v2doc\docs\index.html in a browser:

Generated Dart documentation