Documenting Dart code with dartdoc

Documentation is a critical part of software development, and to encourage good documentation of packages, Dart has the tool dartdoc (https://github.com/dart-lang/dartdoc/), which creates static HTML documentation based on specially formatted code comments. Previous documentation tools for Dart were part of the SDK, while dartdoc is a separate project developed by the Dart team.

It can be installed using pub at the command line:

pub global activate dartdoc

We will take a look at a Dart package project to explore the features of dartdoc. Open the project quakerecord in the WebStorm Editor, and take a look at the file quakerecord.dart:

library quakerecord;
export 'src/quakerecord_base.dart';

This package exports a single file, quakerecord_base.dart, and in this file, the class Processor is declared:

/// A lightweight object to process a raw earthquake feature.
///
/// * Must have valid JSON.
/// * Must be less than 128MB.
///
class Processor {

  // Store for the JSON.
  String _feature;

  /// The state of processing
  bool get processed => true;

  /// The default constructor.
  ///     Processor processor;
  ///     processor = new Processor('{}');
  Processor(String feature) {}

  /// Returns a converted object based on the feature passed into
  /// the constructor [Processor].
  object convert() {
    // A normal comment.
    return new Object();
  }

  /// Changes feature based on partial data.
  /// *BETA QUALITY*
  ///
  /// 1. Estimates end points.
  /// 2. Transforms polarity.
  ///
  void experimentalNewMethod() {}
}

Note the use of the /// triple slash comment style—this is what dartdoc is looking for. The class declaration comments contain an unordered list *, the constructor has a section of sample code, the convert method has a link [] declared to the constructor, and experimentalNewMethod has a numbered list and formatting.

There is also an additional class called ProcessHelper in recordhelper.dart:

/// A helper class to deal with quake feature settings.
class ProcessHelper {

  ///Swaps the data structure.
  void reversePolar() {}
}

To transform the comments into a web page, run dartdoc on the folder containing pubspec.yaml:

 ~/quakerecord/$ dartdoc
Generating documentation for 'quakerecord' into quakerecord/doc/api/
parsing lib/quakerecord.dart...
Parsed 1 file in 15.6 seconds.
generating docs for library quakerecord from quakerecord.dart...
Documented 1 library in 20.0 seconds.
Success! Open quakerecord/doc/api/index.html

A doc sub-folder is created in the project containing a folder named api that holds the documentation. Open the page in your favorite web browser and take a look at the output for the Processor class. Let's have a look at the following screenshot:

Finally, you may be wondering where the class ProcessHelper from recordhelper.dart is located on the generated page. It is not part of the documentation as it is not exported from the package, and because of this, is considered to be a private implementation detail that the consumer of the package does not need to know about.