Hacking Dartdoc for Titles and Descriptions

‹prev | My Chain | next›

A ways back, I hacked the dartdoc tool to include the ability to add a title and description to the generated API documentation. Luckily, I still a have a copy of those changes lying around. Tonight, I am going to try to get them added to the most recent version of the Dart SDK.

Looking back at that old commit, I modified lib/dartdoc/dartdoc.dart. The code seems to have moved a bit since then. The option parsing code looking to now be in pkg/dartdoc/bin/dartdoc.dart. In addition to moving, it looks like there is now a nice API for setting options. I adapt them to set the title of the API documentation:

  argParser.addFlag('title',
      help: 'Title for the documentation.',
      callback: (title) {
        if (title != null) {
          dartdoc.mainTitle = title;
        }
      }
    );

The conditional code comes from my old modifications—hopefully they will still work.

Firing up dartdoc, I see my new option, but also notice that it includes a negation option:

    --[no-]title                  Title for the documentation

I get rid of it with the negatable: false option:

argParser.addFlag('title',
      help: 'Title for the documentation.',
      negatable: false,
      callback: (title) {
        if (title != null) {
          dartdoc.mainTitle = title;
        }
      }
    );

That still doesn't work. I get an error that Flag option "title" should not be given a value. This is when I realize that I should be calling argParser.addOption instead of argParser.addFlag:

  argParser.addOption('title',
      help: 'Title for the documentation.',
      callback: (title) {
        if (title != null) {
          dartdoc.mainTitle = title;
        }
      }
    );

With that, I am able to run the command:

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

And I get nice titles on the resulting documentation:

The description requires a little more work. In addition to the addOption, I also need to modify pkg/dartdoc/lib/dartdoc.dart to include a description setter and to include it in the output. Happily, my changes from earlier this year do the trick nicely.

The result is some pretty (and useful) documentation:

That'll do for a stopping point tonight. Up tomorrow, I will likely continue to muck about with dartdoc. Now that I am in here, I would like to see if I can figure out why triple slashes are no longer formatting code correctly.

Day #558