Dart supports two types of documentation comments:
- single-line (
/// …)
- and multi-line (
/** ... */)
Single-line comments have been chosen as the standard for documentation comments in Dart, since they are generally easier to vertically align and
clearer to read.
They are generally easier to align because following lines in multi-line comments are typically indented by the * character, to make
it clear that they are part of the same comment block.
However, this makes each of the following line of the multi-line comment differently indented than the first line, resulting in a higher future
maintenance cost to keep it correctly aligned.
/** First comment line
* Following comment line, 1 char-indentation
* ...
*/
