This morning I finally got around to fixing numerous problems with the Gecko binary stream documentation. The articles for both nsIBinaryInputStream and nsIBinaryOutputStream were pretty whacked, with totally incorrect descriptions for a number of methods, plus methods completely missing in some places.
These two articles were converted from automatically generated documents, and the result exposes some of the inherent limitations to automatic documentation generation. If you look at the IDL for these two interfaces, you’ll see that the comments are not very thorough. Individual methods have no comments; instead, the comments are for groups of methods (at best). In addition, not all parameters have comments describing them.
The result is that the importer tool has to make guesses in a lot of cases, and the results are often sub-optimal. In this case, the last available method-describing comment was duplicated for each method added to the document, resulting in every method in nsIBinaryInputStream being listed as returning Boolean value read from a single byte from the stream.
While there’s certainly a place for automated tools in documentation, there always needs to be a human reviewing the output, because unless you can guarantee that the comments and markup in the IDL files is correct, the output won’t be. It’s clear that these two articles, for example, were never really reviewed.
This is why I prefer to take a slow and measured pace as we investigate automation of documentation tasks. It’s very easy to automatically generate bad documentation. It’s very, very hard to automatically generate good, reliable documentation. In my opinion, it’s not worth doing if you can’t do it right.
That’s why my feeling is that using tools to do an initial, automatically generated rendition of a document is fine, but from then on, it should be maintained by human writers and editors. That way, we can better control quality. And every article needs to be reviewed by at least one human editor as well — preferably both a writer and an engineer — in order to ensure accuracy.
I’d like to have a tool that can take IDL input and generate output formatted following our interface reference style guidelines. Then we can clean up the output and post it. That would help us get our content filled out faster. We just can’t blindly post everything it generates.