Dartdoc and Missing Code Formatting

‹prev | My Chain | next›

I am ready for the next phase in my master plan now that I have Hipster MVC published in the very exclusive and difficult to get into Dart Pub. OK, all I really had to do was submit a request, but they made me change almost 2 things before it was accepted. Anyhow, onto the next phase…

Documentation.

I really like the Dartdocs documentation format that comes bundled with the Dart SDK. It makes for very pretty documentation that is readily available. It actually makes me want to write documentation:

When last I played with dartdoc, I made several changes to the tool to make everything just so.

Tonight, I am going to revisit the tool. Hopefully, I can now use the stock dartdocs without any modifications. So I give it a whirl:

➜  hipster-mvc git:(master) ~/local/dart/dart-sdk/bin/dartdoc lib/*.dart  
Documented 6 libraries, 15 types, and 134 members.

That is actually fairly promising. Way back when, I would see 600+ types, and 5000+ members as dartdoc would try to include core documentation as well as the current library documentation.

That seems to do a pretty decent job. I pick up the changes to my code (e.g. url and length are getters without empty parens now):

I also like how inherited documentation is included—that is a nice touch.

There are a couple of problems, or nit-picks, or me being fussy. On the entry page for the documentation, the title is now "Dart Documentation" and there is no explanation of the library:

Compare that to the hacked version from earlier this year:

(the sidebar is generated for both, but not view-able when I am browsing the new stuff at file://)

I think I will worry about that tomorrow. For now, I would like to fix the code formatting. Above, I have nicely formatted code samples. Now I have a jumbled mess:

Previously, dartdoc would format the code if I indented it by four spaces:

  /// Application routers must subclass [HipsterRouter], definining at least the
  /// [routes] getter:
  ///     class MyRouter extends HipsterRouter {
  ///       List get routes() =>
  ///         [
  ///           ['page/:num', pageNum, 'page']
  ///         ];
  ///       //

It takes a bit of trial and error, but I eventually figure out that I need to use slash-star comments instead of triple slashes now:

/**
  * The router exposes named events on which listeners can wait. For example,
  * if the router has a "page" route, the event will be available on the
  * 'route:page' event:
  *
  *     HipsterRouter app = new MyRouter();
  *       app.
  *         on['route:page'].
  *         add((num) {
  *           print("Routed to page: $num");
  *         });
  */
  RouterEvents on;

With that, I have my code highlighting back:

I cannot complain too much about this change. I rather prefer the single star version to the triple slash. There is less noise in the code and it looks more like something that I might have written myself. It seems I have some documentation to reformat...


Day #557