Keep documentation up to date with a doc generator

A very important new feature for project JAM, is to provide better visibility into the expiration time of a Jar entity. It also happens to be C01t’s very first end-to-end feature. He is responsible for designing, implementing, and testing in. Therefore, C01t is determined to do a great job.

As a first step, C01t decides try and improve the Jar access APIs. He schedules a brain storming session with Aaron and JP. After a bit of debate they agree to start with enhancing the GetJar API.

For GetJar, C01t will add support for the caller to specify the desired format for datetime fields in the response. First, C01t adds a new optional “options” parameter to the GetJar method. While modifying the method signature, he also adjusts the docstring.

  def GetJar(id, options = None):
    """Retrieve meta-data of a Jar entity.
    
    Args:
      id (str): The unique identifier for the Jar entity.
      options (GetJarOptions): The config values used to customized API behavior.

    Returns:
      Jar: Entity meta-data.
    """
    ...

Furthermore, he defines the value object GetJarOptions. Since he wants a smother code review experience, he follows the style of the module and adds a docsting for the new class.

from typing import NamedTuple

class GetJarOptions(NamedTuple):
  """ Value object used to pass options to the GetJar API.

  Attributes:
    date_time_format (str): The format to use for returning datetime fields.  
  """

  date_time_format: str

And to verify his changes he runs make. In the command output C01t notices that a tool called sphinx was run. So he googles “sphinx python” and finds out that the tool is popular doc generator for python. C01t explores the files generated by sphinx. He is pleasantly surprised to discover that the API changes he made are reflected in the doc thanks to the docstrings he wrote.

Generate documentation from code comments

C01t amended the documentation for project JAM without even knowing he was doing so. The documentation generator picked up his docstrings changes and refreshed the docs. Because the docstrings are stored in the code files, C01t updated them when he modified the code. As a result, code and docs changed in lockstep.

Pretty much all popular programming languages today have a doc generator. Following is a list of recommended doc generators.

python

The doc generator for python is sphinx. Sphinx uses reStructuredText as its markup language. Furthermore, you can use the autodoc extension of sphinx to include docstrings into the generated docs. In addition, python has a style guide for writing docstrings, PEP 257. pydocstyle validates that your docstrings follow PEP 257 conventions.

Once you write your docs using sphinx, you can host them publicly on Read the Docs.

sphinx: website, project, docs, pypi package
pydocstyle: project, docs, pypi package

ruby

One of the most popular doc generators for ruby is YARD. In keeping with the tradition of ruby, you can easily customize and extend YARD. In addition, the tool is fully compatible with other ruby documentation formats. Most notably, you can use it to process RDoc formatted documents.

And if you are looking for service to host documentation for your ruby projects, you can do so at YARD powered RubyDoc.info.

yard: website, project, docs, gem, getting started guide

go

Go, in the form of godoc, has the most tightly integrated doc generator. Not only does godoc parse comments, but it also parses the code itself. Furthermore, the comments read by godoc do not have to follow a special syntax. Instead the comments are governed by a small set of conventions very well explained in the godoctricks tutorial.

godoc.org is the official documentation hosting solution for Go packages. Adding a package to godoc.org is as simple as searching for the package by import path.

godoc: project, docs, godoc-tricks tutorial

java

JavaDoc, the doc generator for Java is the original doc generator. The tool comes bundled with all JDKs and SDKs. So you don’t need to download it separately. To learn how to write documentation comments for JavaDoc follow the official guide.

For your open source Java projects you can host JavaDocs on javadoc.io.

JavaDoc: website, docs

javascript

To document your javascript projects a good choice of generator is ESDoc. The tool processes your source files and parses documentation tags from comment blocks. It supports tags very similar to those used by JSDoc. Due to its core plugin architecture, you can add missing functionality to ESDoc. You can improve the quality of your source code documentation using the “doc coverage” metrics and linting feature of the tool. In addition, you can augment the docs further by leveraging ESDoc‘s ability to import description strings from test code and integrate content from Markdown files into the generated docs.

You can host docs for your javascript libraries on the ESDoc Hosting Service.

ESDoc: website, project, package

php

phpDocumentor is the the de-facto standard doc generator for php. Using phpDocumentor you can generate docs directly from comments in your source files. Like with most other generators you can customize the look and feel of the generated docs via a flexible templating system. In addition, phpDocumentor can perform static analysis of your code and produce graphs and reports.

phpDocumentor: website, project, docscompose package

c#

The c# compiler has built in support for generating documentation from xml documentation comments. The compiler generated file then needs to be processed with a tool such as Sandcastle to generate the final docs. Another useful tool for writing xml documentation comments is automineer. automineer generates and updates xml documentation blocks for your code.

Sandcastle: website, project, docs
automineer: website, docs

---

Image courtesy of: Bank Phrom