Thursday, November 1, 2012

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…


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


  1. To my knowledge, both /// line comments and the block comments should be equivalent and allow for all the same markdown formatting (code commenting, linking etc). So it sounds like a bug to me that your /// formatted comments didn't create the code block with the 4 spaces but the:
    */ version did.
    That said I have always preferred the /** */ style comments over the triple slash for dartdoc comments.

    Also you have a couple of options for generating/viewing comments. In particular you can launch something like: python -m SimpleHTTPServer in the doc directory you can browse to it with localhost:8080 type page and get the content served properly. Or if you want to provide static pages which are a little larger but use little in the way of server-requests you can use the 'dartdoc --mode static lib/' to generate the files.

    1. Yah, I think it might be a bug. For the rest of my docs, I did a straight search and replace of '///' with * then added /** and */ around them. And magically, the code formatting returned. I'll likely do a little more digging tonight to get a better idea of what is going on here.

      I'm serving the docs in the wild with GitHub Pages: So I'll probably get a jekyll server up and running if I want to verify the sidebar stuff.

  2. Nice post...
    Found a eclipse plugin for eclipse IDE users, to directly copy the code as HTML.