doxygen (was: Re: [Nut-upsdev] NUT and Automake)

[Peter Selinger]

Charles Lepple wrote:
> 
> On 10/15/06, Peter Selinger <selinger at mathstat.dal.ca> wrote:
> > I have converted NUT's build system to Automake/Libtool. Right now,
> > the new build system is contained in the "automake" branch, at:
> 
> Wow... this is really nice. Thanks for taking the time to do the conversion.

Thanks. It actually was much more work than I anticipated. Primarily
because I had to understand all that stuff in ./configure.in, and also
I had to figure out all this stuff that NUT installed that I never
cared about before.
 
> > drivers/Doxyfile        - this seems to belong to Charles. Perhaps
> >                           related to auto-generating documentation
> >                           for the tripplite_usb driver? It probably
> >                           should go in another directory, and with
> >                           a better name.
> 
> The name 'Doxyfile' is actually the default name for the doxygen
> configuration file.
> 
> That said, doxygen is not really good at documenting source code for
> projects that have multiple programs (and multiple 'main()'
> functions). What might be useful is to have a template Doxygen.in that
> can generate documentation for a given driver (as specified in a
> ./configure parameter). You can move it elsewhere, but I will just
> have to adjust the source paths.

Perhaps it should go in the man/ directory, and be called something
like tripplite_usb.doxy? This is assuming that there would be one such
file for each driver/man page. If there is only a single file for
all supported man pages, then the name Doxyfile would be useable. 

> Eventually, I would like to put some more documentation into the core
> NUT files, since there are a number of assumptions that aren't obvious
> if you are just reading driver code.
> 
> The man page for tripplite_usb is actually generated with the Perl
> POD-to-man translator, but I didn't want to put another dependency
> into the old build system - so I just rebuilt the man page by hand.
> This is another candidate for automation.

Yes, assuming that all maintainers who might want to build this file
have pod2man available. It's easy to cause "make dist" to distribute
both the doxy file and the resulting man page, so that tarball-users
will not have to rebuild it.

By the way, with the new "make distcheck" mechanism, it should be
relatively easy to automatically generate a "daily tarball", or
perhaps to trigger such a tarball to be build after each commit.  Do
you know how to hook into SVN to trigger such a post-commit action?
(Moreover, if "make distcheck" fails, then a bug has been immediately
discovered).

-- Peter