Nut upsdev - Jan 2007 - Doxygen API documentation

One thing that would be handy for driver developers (or for myself, at
the very least) would be having some API documentation for the core
NUT functions.

Here is an example of Doxygen's output:

http://www.ghz.cc/~clepple/libhid/doc/html/hid_8h.html

The two main categories of API documentation that I see are the
internal NUT functions needed for writing drivers, etc., and the
external libraries (libupscli and libupsconfig). Doxygen is really
meant to document only one program at a time, so I'm not sure how we
would handle the different binaries like upsc, upsd, upsrw, etc., but
that's for down the road.

Thoughts?

I am open to suggestions for other similar tools, but Doxygen is
readily available, and the syntax should be familiar to anyone who has
used Qt's documentation tool or JavaDoc.

In a lot of cases, there are already comments by functions, but they
will not be picked up by Doxygen unless the structure is tweaked a
bit.

-- 
- Charles Lepple

2007/1/14, Charles Lepple <clepple@gmail.com>:
> One thing that would be handy for driver developers (or for myself, at
> the very least) would be having some API documentation for the core
> NUT functions.
>
> Here is an example of Doxygen's output:
>
> http://www.ghz.cc/~clepple/libhid/doc/html/hid_8h.html
>
> The two main categories of API documentation that I see are the
> internal NUT functions needed for writing drivers, etc., and the
> external libraries (libupscli and libupsconfig). Doxygen is really
> meant to document only one program at a time, so I'm not sure how we
> would handle the different binaries like upsc, upsd, upsrw, etc., but
> that's for down the road.
>
> Thoughts?
I still have that in mind, but it's part (on my side) of the
Documentation rewrite.
What I see is a Developer Manual, for driver and client application,
that will federate all the existing (or about to exist) docs.
For the doxy part, I would see multiple doxy file (ie 1 for each lib,
and 1 for the driver API), and all these link from the Developer
Manual...

I don't think the other binaries need to be doxygen'ed, but there is
definitely a need for documenting how nut is architectured for
maintainance purpose.

Arnaud
-- 
Linux / Unix Expert - MGE UPS SYSTEMS - R&D Dpt
Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org/
Debian Developer - http://people.debian.org/~aquette/
OpenSource Developer - http://arnaud.quette.free.fr/