Subject: Re: FSBs and mechanized documentation
From: Ian Lance Taylor <ian@airs.com>
Date: 08 Mar 2006 13:28:15 -0800

Rich Morin <rdm@cfcl.com> writes:

> Nonetheless, I haven't found much evidence of these tools being
> used in the Open Source community.  I would be interested in
> hearing about projects that are using these tools, including
> feedback on the perceived benefits and problems.

libstdc++ is an example of a project which uses doxygen.  For example:
    http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html

BFD uses a hand-grown tool with similar effects.  For example,

    http://sourceware.org/binutils/docs-2.16/bfd/BFD-front-end.html#BFD-front-end

is generated directly from the BFD .c and .h files.

My experience is that tools like doxygen can be useful for library API
documentation, provided somebody adds organizing text.  I don't find
them to be useful for program documentation, or for internals
documentation, except when the program is designed as a collection of
independent libraries.  These tools are quite good at describing
simple interfaces; they are much less helpful when describing complex
interfaces, such as when routines depend upon a number of global
variables.

What I find equally helpful is tools which let you quickly look at the
function/class definition, and at all the places where the
function/method is called.

Ian