Experimental Physics and
Industrial Control System

Ralph Lange <[email protected]> · Tue, 15 Mar 2011 17:49:39 +0100

On 15.03.2011 17:20 Jeff Hill wrote:

I would encourage considering the use of a standard tool like
doxygen, I think once you start writing in-line documentation it should
make future maintenance easier, although I've rarely used it myself
because introducing it after-the-fact is hard.

Such tools have been around for a long time. People were using them on the
VAX when I started here in 1986. I'm sure they have learned a thing or two
since then so perhaps I should look closer at doxygen. The argument for use
of doxygen type programs is that programmers are more likely to work on
their programming language source files, and so if we store the doc there
also then maybe they will keep it current. There can also be a standard,
consistent, format. The downside maybe is that every manual reads like a
reference manual, and we are less likely to have a tutorial. We are maybe
more likely to create human friendly documentation with concept structured
indexes and html tables if the html is structured by a human?

We won't (ever) win a Pulitzer with our documentation, either way.

Doxygen (which looks and works a lot like Javadoc) creates very nice reference documentation from comments in the source files, which is especially

nice for library APIs that you want other people to use.

There are IDEs that help you create doxygen for C/C++ very similar to helping you create Javadoc.

The internal link references in the html code are created automatically by doxygen. These are always relative, so that you can move around the created

doc.

But again: Doxygen is for creating code documentation. Tutorials, user guides, and fiction should use other tools.

~Ralph

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System