Software Design by Example 16: Documentation Generator


Many programmers believe they’re more likely to write documentation and keep it up to date if it is close to the code. Tools that extract specially-formatted comments from code and turn them into documentation have been around since at least the 1980s; Chapter 16 of Software Design by Example builds on discussion in earlier chapters of turning code into a data structure to extract Markdown from comments and turn it into HTML.

Mapping comments to documentation
Figure 16.2: How comments in code map to documentation in HTML.

While tools like this are useful, I wish they didn’t need to exist. Instead, I wish our languages would allow us to write things like:

const name = (args) => {
    …do things…
with documentation {
    Lorem ipsum dolor sit amet,
    [[consectetur]] adipiscing elit,
    sed do eiusmod tempor incididunt ut labore
    et dolore magna aliqua.

where the names of parameters and other functions are automatically cross-linked and [[…]] or some similar syntax creates an external link and so on. doctest-style tests could be put in another block, and I’m sure people would find other uses for this as well. In a better world than this…

Terms defined: accumulator, block comment, deprecation, doc comment, line comment, slug.

And in answer to a question online, no, I didn’t draw UML diagrams anywhere in this book: there wasn’t a single case where one of the standard diagram forms felt like the best way to present what I wanted to convey. I don’t think it’s because my programs are too small—there are lots of places in the book where I wish I’d drawn more, but I was wearied by the thought of having to maintain them. I’ve grumbled about this in [1, 2, 3, 4], and frankly, I’ll start believing Silicon Valley is serious about being desperate for more programmers when I see companies putting some real resources behind tools to help teach them better.