DaedTech

Stories about Software

By

Generate Documentation from Your Build

Editorial Note: I originally wrote this post for the SubMain blog.  You can check out the original here, at their site.  While you’re there, have a look at GhostDoc.

Before I get down to the brass tacks of how to do some interesting stuff, I’m going to spin a tale of woe.  Well, I might have phrased that a little strongly.  Call it a tale of corporate drudgery.

In any case, many years ago I worked briefly in a little department, at a little company that seemed to be a corporate drudgery factory.  Oh, the place and people weren’t terrible.  But the work consisted of, well, drudgery.  We ‘consulted’ in the sense that we cranked out software for other companies, for pay.  Our software plumbed the lines of business between client CRMs and ERPs or whatever.  We would write the software, then finish the software, then hand the software over, source code and all.

Naturally, commenting our code and compliance with the coding standard attained crucial importance.  Why?  Well, no practical reason.  It was just that clients would see this code.  So it needed to look professional.  Or something.  Didn’t matter what the comments said.  Didn’t matter if the standard made sense.  Compliance earned you a gold star and a move onto the next project.

As I surveyed the scene surrounding me, I observed a mountain of vacuous comments and dirty, but uniform code.

My Complex Relationship with Code Comments

My brief stay with (and departure from) this organization coincided with my growing awareness of the Software Craftsmanship movement.  Even as they copy and pasted their way toward deadlines and wrote comments announcing that while(x < 6) would proceed while x was less than 6, I became interested in the idea of self-documenting code.

Up to that point, I had diligently commented each method, file, and type I encountered.  In this regard, I looked out for fellow and future programmers.  But after one too many occasions of watching my own comments turn into lies when someone changed the code without changing the comments, I gave up.  I stopped commenting my code, focusing entirely on extractions, refactoring, and making my code as legible as possible.

I achieved an equilibrium of sorts.  In this fashion, I did less work and stopped seeing my comments become nasty little fibs.  But a single, non-subtle flaw remained in this absolutist approach.  What about documentation of a public (or internal) API?

Naturally, I tried to apply the craftsmanship-oriented reasoning unilaterally.  Just make the public API so discoverable as to render the issue moot.  But that never totally satisfied me because I still liked my handy help screens and Intellisense info when consuming others’ code.

And so I came to view XML doc comments on public methods as an exception.  These, after all, did not represent “comments.”  They came packaged with your deliverables as your product.  And I remain comfortable with that take today.

Generating Help More Efficiently

Now, my nuanced, evolved view doesn’t automatically mean I’ll resume laboriously hand-typing XML comments.  Early in my career, a sort of sad pride in this “work harder, not smarter” approach characterized my development.  But who has time for that anymore?

Instead, with a little bit of investment in learning and tooling, you can do some legitimately cool stuff.  Let me take you through a nifty sequence of steps that you may come to love.

GhostDoc Enterprise

First up, take a look at the GhostDoc Enterprise offering.    Among other things, this product lets you quickly generate XML comments, customize the default generation template, spell check your code, generate help documentation and more.  Poking through all that alone will probably take some time out of your day.  You should download and play with the product.

Once you’re done with that, though, consider how you might get more efficient at beefing up your API.  For the rest of this post, I will use as an example my Chess TDD project.  I use this as a toy codebase for all kinds of demos.

I never commented this codebase, nor did I generate any kind of documentation for it.  Why?  I intended it solely as a teaching tool for test driven development, and never packaged it for others’ consumption.  Let’s change that today.

Adding Comments

Armed with GhostDoc enterprise, I will first generate some comments.  The Board class makes a likely candidate, since that offers theoretical users the most value.

First up, I need to add XML doc comments to the file.  I can do this by right clicking in the file, and selecting “Document Type” from the GhostDoc Enterprise context menu.  Here’s what the result looks like.

ghostdoccomments

The default template offers a pretty smart guess at intent, based on good variable naming.  For my fellow clean code enthusiasts out there, you can even check how self-documenting your code is by the quality of the comments GhostDoc creates.  But still, you probably want to take a human pass through, checking and tweaking where needed.

Building Help Documentation

All right.  With comments in place for the public facing API of my little project, we can move on to the actual documentation.  Again, easy enough.  Select “Tools->GhostDocEnterprise->Build Help Documentation” from the main menu.  You’ll see this screen.

helpgeneration

Notice that you have a great deal of control over the particulars.  Going into detail here is beyond the scope of my post, but you can certainly play around.  I’ll take the defaults and build a CHM help file.  Once I click “OK”, here’s what I see (once I go to the board class).

chmfile

Pretty slick, huh?  Seriously.  With just a few clicks, you get intelligently commented public methods and a professional-looking help file.  (You can also have this as web-style documentation if you want).  Obviously, I’d want to do some housekeeping here if I were selling this, but it does a pretty good job even with zero intervention from me.

Do It From the Build

Only one bit of automation remains at this point.  And that’s the generation of this documentation from the build.  Fortunately, GhostDoc Enterprise makes that simple as well.

Any build system worth its salt will, of course, let you hook command line invocations into your build.  GhostDoc Enterprise offers one up for just this occasion.  You can read a succinct guide on that right here.  With a single command, you can point it at your solution, a help configuration, and a project configuration, and generate the help file.  Putting it where you want is then easy enough.

Tying this in with an automated build or CI setup really ties everything together, including the theme of this post.  Automating the generation of clean, helpful documentation of your clean code, building it, and packaging it up all without human intervention pretty much represents the pinnacle of delivering a professional product.

Sort by:   newest | oldest | most voted
Michael Robinson
Guest

Great article. Another real value add (for API development) is automatic REST endpoint documentation generation.

It’s extremely helpful for larger/long-term projects and takes a ton of time to do manually.

In node.js-land when using hapi, hapi-swagger will generate interactive live API documentation based of your declared REST routes (link: https://github.com/glennjones/hapi-swagger)

Erik Dietrich
Guest

Thanks! And, agreed on the generation of API documentation (and examples) for REST endpoints.

lb
Guest

“…intelligently commented public methods and a professional-looking help file”? Looking at the screenshot from the CHM file. “Doeses the piece exist at”; or “GetMovesFrom” => “Gets the moves from”. That’s neither intelligent nor professional-looking

Erik Dietrich
Guest

The next sentence talks about the need to do some housekeeping, which is how I’d categorize fixing up the instances where the language processing doesn’t generate the right looking thing.

Peter Morlion
Guest

I’ve worked with GhostDoc in the past and found it to generate a lot of cruft. In my opinion, it led to properties like ‘PieceCount’ being commented with ‘Gets the piece count’. This adds no value for me. I try to add comments only when the intent or behavior of a member isn’t clear from the public API. But first you should try to make the member more clear. That’s my opinion at least.

Erik Dietrich
Guest

I would concur that generating XML doc comments generates no value for me — but my aim here is to generate value for API clients rather than for myself.

Peter Morlion
Guest

Yeah, I was going to add that it’s different if you’re building something like a library. But I thought I was going on too much of a rant and decided to stop 🙂

Joshua McKinney
Guest

I don’t actually think it does make a difference whether it’s personal or a library.

Unedited ghost doc comments are beyond useless IMO. As a placeholder, they’re no better than // TODO add a comment here.

As a consumer they add nothing more to my learning about a class than I already knew by reading the names of the identifiers.

If you want or need these sorts of comments, they should be driven directly from the unmodified uncommented code at build time, not as part of the source.

wpDiscuz