Documentation Generator

The idea of documentation generators seem to date back to 1995 with Javadoc.

The basic idea is that "special" comments will generate HTML (or PDF or…) documentation files when processed by a documentation generator.

Originally, Javadoc was motivated by placing this documentation on the "World Wide Web". Therefore, using HTML in the comments was an obvious design decision.

However, it seems we now realize…that's not the best idea. The general consensus appears to have rallied around using Markdown for the documentation comments.

In short, the basic ingredients:

• Some way to demarcate a comment as a documentation comment. Javadoc uses /** ... */, and this seems to be a common convention.
• A choice of markup for the content of the documentation comment. This is usually some flavor of Markdown, but Javadoc's shadow looms large even today.
  • Consider how you'll link to other identifiers. I've seen some Markdown systems use [`identifier`] (the identifier surrounded by backticks within square brackets)
• A program to read a source file, seek out the documentation comments, and determine what it is documenting exactly.

The intent of a documentation comment is to document the API, the contract for the function (or class or whatever).

It is not literate programming.

It's the quickest way to say to another programmer, "Here's how to use this function."

With proof assistants, the usefulness of documentation comments is to communicate the "subjective substratum" — the informal discussions of motivation, analogies, problems, examples, intuitions, false leads, etc.

This plays a very different role than in a program. But it is very important.

Without these, a proof script lacks "texture" (as linguists would call it): it's just a grocery list of propositions.

• Implementing a Documentation Generator for Javascript
• Elm's doc comment conventions
• ocamldoc for a different take
• Rosetta Code comparison of doc comment conventions
• PEP-257 for docstring conventions in Python
• JEP-467 for proposal of Markdown documentation comments in Java
• Ashn's Crafting Cdoc blog post series