API Documentation

Creating API documentation is a tedious task at best. Automating this process removes most drudgery involved. Programmers glimpse at API documentation at several points throughout the day. We do this to confirm doubts or to make sure that the function was in fact returning an integer type. Not only does automated documentation generation safe us effort, it is also a time saver. Is there a need for human intervention, given that we have tools at our disposal to write API documentation for us? Are the tools really that good? And if not, if they're still lacking in one respect or another, will they ever replace us entirely?

What exactly do automatic code generators do? Put simply, they collect oodles of software system information and render it in a programmer-friendly format. The basic idea is to parse the source code tree of the project and write the documentation output. The format of the documentation can be anything really, but common forms are PDF and HTML. HTML is probably the best in most situations as it is easier to navigate and usually looks better.

Automatically generated API documentation depends largely on code higher-level code structures, not necessarily the low-level file operations and so-on. Modules, classes, and functions are the preeminent descriptions that make API documentation useful. Finer details about these high-level units can also be included by the documentation generator. Function parameters, return types, and class attributes - all relevant things programmers want to read about.

We annotate these these high-level language constructs using comments which are also captured by some of these documentation-generating tools. If you use Python, you have the added privilege doc-strings, which are part of the code objects themselves. In either case, you, the developer, have the ability to extend the content of the generated API documentation. You're effectively writing documentation and code at the same time. Sounds great, doesn't it? The difficulty with this approach is intent. Are code documentation and API documentation the same thing?

Documenting code is all about explaining the "nitty-gritty" to those with the misfortune of reading your code. You've agonized over strenuous details and need to walk any reading eyes through it. Probably this isn't the kind of thing we care to see in API documentation. If I need to look up something specific in the API documentation, I don't want to be bothered by big chunks of "this attribute needs to be reset after the....". Encapsulation also applies to documentation.

How do programmers format the comments lifted from the code by generators? Documentation tools do a fine job of formatting language constructs like classes, functions, variables, etc. What they can't do is format text embedded inside an explanation. In the documentation of a function, I'll sometimes want to see a brief paragraph that tells me why the state of the file object stored in an output stream queue changes. It is helpful to format text inside these explanations as well as link to other documents. A popular format for writing API documentation seems to be reStructuredText. What this amounts to is programmers using a markup language within the programming language. This adds an unnecessary burden - especially since comments should be geared more toward the low-level.

There really is no substitute for automatically generating the code structure used in API documentation. The only alternative is to do it manually, which is excessively tedious. But at the same time manually writing the API documentation gives you freedoms you don't necessarily have when generating it via code comments. For one thing, you're not legally bound for life to a single tool. You can format as you deem necessary. You're also not restricted by the configuration constraints generation tools impose - you can document as much or as little code as you want. Whichever method you choose, just be sure that good documentation is the result.

Documenting Code

There are many reasons why developers are told to document their code. As Jason Baker shows, many of these common reasons for commenting code are mythical. That is to say, the added benefit for documenting a piece of code may be misguided in certain contexts.

For instance, comments need to be updated as the code is updated. This means more in-depth maintenance for comments. Unless you strive to keep comments simple and generic enough. This is usually the best approach.

Often, the best way to document your code is to spend a short amount of time and overview your code as though you were someone else. If that person needs an explanation for some section of code, give it to them. But keep it simple.

You can still document trivial methods that are self explanatory. The best reason for doing this is consistency.

Documenting With Sphinx

Whether a developer is writing an application in Python, or any other language, API documentation is an absolute must. The API documentation should go without saying these days. If a developers asks if they are a requirement, the this fact hasn't been driven home hard enough. Other developers shouldn't need to sift through a mountain of code just to find a function signature. Especially with the nice output that is available with the generation tools available.

Sphinx is just such a tool, geared toward generating API documentation output for Python applications. One of the nice things about Sphinx is its' own API documentation. There isn't much on the how-to end but every supported language construct is there and it is made clear how to use it.

Another quality of Sphinx is that it is general purpose enough to use with languages other than Python. As long as the concepts are somewhat similar to those found in Python, it can work. And this is helpful for developers if a single documentation generation tool can be used for all output.

Developers do, however, have a big decision to make when considering Sphinx as the documenter of choice. Sphinx requires that RST documents that contain the actual API documentation to be maintained. That is, Sphinx cannot generate API documentation based on the doc-strings of the source code. Many other documentation generation tools can do this, but the overall quality of the Sphinx output is far above anything else.

How to manage technical documentation for varying levels of competency?

An interesting question on slashdot asks exactly this. Two things spring immediately to mind for me:

1. Trac
2. Is this possible?

The Trac wiki system would be my first choice simply because I'm familiar with it. Anyone with moderate Trac experience can teach the concepts to other people fairly easily. Developers and anyone else using the system.

So, the basic problem re-stated; "how do I provide a simple and easy way for people of with different levels of knowledge toward a given subject access to that information?". Using Trac, you could start by getting all required content into a page. This includes every possible detail imaginable.

Next, suppose we have written a Trac plugin that defines processors you can use to wrap around sections of text based on the required expertise. For instance, you could have the following processors defined:

• Expert-topic
• Intermediate-topic
• Moderate-topic
• New-topic

The second part of this theoretical plugin would need to extend the user accounts to allow the ability to specify what the user knows and at what level. Of course, each page would also need to be categorized as well.

The question of is this possible comes not from the technical end but from the business side of things. My answer to this is another question. How accurately can users' knowledge for a given topic be rated? This problem is eliminated if we were allow users to rank themselves in regards to topic competence.

boduch API

The boduch API documentation is now available.