Blogs

I wanted to add SCGI support to Woof! under Apache on Windows. Not finding a suitably recent version of a mod_scgi binary for Windows, I thought I would build it myself. The eventual steps were simple enough but for someone building an Apache module for the first time on Windows (Linux is better documented and simpler) getting there was a bit of a runaround of following broken links and outdated information.

So here are the steps for future reference:

One of the features of the Ruff! documentation generator is automatic discovery of the entire callable interface of a class, including methods that have been inherited or mixed-in. In addition to enumeration of the available methods, this requires linking to the exact method implementation that is invoked for a method when multiple superclasses and mix-ins implement the same method.

Ruff!’s primary purpose in life is to extract program reference information and it tries to do that as well as it can. It is not intended to be used for writing tutorials, user guides or other complex documents where the primary input is by necessity manual. Attempting to reproduce some of that functionality will only dilute its purpose.

The initial release of Ruff! did not produce documentation in the final output format. Instead it generated output in a format that can be fed into existing documentation generation system. Ruff! still supports these external tools but experience has shown the external tools are not quite up to snuff when it comes to cross-referencing and linking of names in a inheritance hierarchy and multiple scopes. Fully qualifying all names is a partial solution but results in very cluttered documentation.

Documentation may be produced in different formats, for different purposes, targeting different media and by people with different goals. A documentation generator should therefore try not to impose constraints on the layout, order or general structure of its output.

Unless the merged interface, including inherited methods, mix-ins, and forwards, are clearly documented and linked, documentation related to classes and similar is even more of a headache for the reader than the programmer.

It is tedious enough to write documentation without having to repeat what should already be deducible from the code.

The act of documenting source code should not come in the way of the clarity of the source itself.

One of the more painful exercises a programmer has to go through is that of documenting code. Unlike the more intellectually satisfying activities of design, coding, and even debugging, documentation is seen, with good reason, as a grind. Moreover, burdensome enough the initial documentation effort may be, there is the additional ongoing chore of  maintaining the documentation as the software grows and programming interfaces evolve. Documentation through run time introspection may help.