A tool for maintaining Dart comments

by Flutter Awesome

A tool for maintaining Dart comments (daco).

This package is in an early stage of development. Please file anissue if you find a bug or start a discussion if youhave a question.

Getting started

  1. Make sure you have a recent version of NodeJS (>=14) installed and on thepath. daco uses prettier to format Markdown.

  2. Install daco globally:

    dart pub global activate daco

  3. Format the Dart files within the current directory:

    daco format .

Formatting

daco formats documentation comments in Dart files.

prettier is used to format comments as Markdown. This means that the conventionsof prettier are applied, such as using ** to bold text instead of __. A nicefeature of prettier is that Markdown tables are pretty-printed.

Prose is reprinted to optimally fit within the specified line length (defaultsto 80):

- /// The quick brown fox     jumps over the lazy dog. The quick brown fox jumps over the lazy dog.+ /// The quick brown fox jumps over the lazy dog. The quick brown fox jumps over+ /// the lazy dog.  const foo = 'bar';

This is useful when writing and updating documentation comments and an editpushes some text beyond the preferred line length.

Embedded Dart code

Fenced code blocks that are tagged with dart are formatted as Dart code.

  /// A top level constant.  ///  /// ```dart- /// const fooList = [foo,];+ /// const fooList = [+ ///   foo,+ /// ];  /// ```  const foo = 'bar';

The Dart code is parsed and if it contains syntactic errors they are reportedwith correct line and column numbers. This provides a basic check for this code,ensuring it is at least syntactically correct.

If the code does not represent a valid Dart file, formatting of it can bedisabled by tagging it with no_format:

/// A top level constant.////// ```dart no_format/// print(foo)/// ```const foo = 'bar';

Formatting of Dart code and documentation comments is recursive. That meanscomments in fenced code blocks containing Dart code are formatted too.

Dartdoc tags

Dartdoc supports tags for features such as templates. Dartdoc tags should beseparated from other content with an empty line, since prettier does notrecognize them as special and formats them as simple text:

/// A top level constant.////// {@template foo}////// The template content.////// {@endtemplate}const foo = 'bar';

When formatting a preexisting codebase special attention should be paid to thelocation of dartdoc tags after formatting.

TODO

  • Support standalone statements in embedded Dart code
  • Support formatting of end of line comments
  • Support disabling formatting for a comment

Ideas

  • Integrate formatting with IDEs
  • Analyze comments
    • Spelling
    • Punctuation
  • Format Dart code in Markdown files
  • Analyze Dart code embedded in Markdown
  • Test Dart code embedded in Markdown
  • Embedded templates in Markdown
    • Template is commented out
    • Below template, output of template is injected/updated

• Twitter@GTerwesten • Medium@gabriel.terwesten

GitHub

View Github