[Nut-upsdev] Nut-upsdev Digest, Vol 88, Issue 22

[Arnaud Quette]

2012/10/29 <VaclavKrpec at eaton.com>

> Hello everybody,
>

Hi Vasek


> just a few notes to the doxygen X man issue:
>
> 1/ AFAIK doxygen can generate man pages, so why don't
>    we just generate them and decide then whether they
>    are ill fitted or usable...
>
> 2/ I'd definitely use doxygen when possible; I mean I don't
>    know any alternative that's able to do (at least partial)
>    validation of the documentation with the source
>
> 3/ I have some experience with using doxygen for C++ code
>    documentation and must warn you that there may be a need
>    for some sacrifices; doxygen only does (quite poor) syntax
>    analysis and is more C-suited; with certain C++ constructs,
>    it fails quite flagrantly (at least the version I've used),
>    an example being instantiation of a static object with
>    global visibility scope, using constructor with arguments,
>    e.g. something like this:
>
> MyClass my_var(arg1, arg2);
>
>    doxygen misinterprets this as declaration of a function
>    and requires you to document the parameters (you need to
>    get rid of that using \cond and therefore you loose
>    the possibility of documenting the variable).
>    However, it's still the best I know.
>

thanks for your comments.
we are still trying to evaluate the best tool for documenting source code.
Note that, as told, manpage are limited to C functions.

as you say, doxygen is probably the best of bread.
what would be very nice is a bridge between doxy and asciidoc... though
I've not searched around that.
I see doxygen limited to documenting the core functions (for maintenance
purposes) and client APIs.

cheers
Arnaud
-- 
Linux / Unix / Opensource Engineering Expert - Eaton -
http://opensource.eaton.com
Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org
Debian Developer - http://www.debian.org
Free Software Developer - http://arnaud.quette.fr
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20121029/5eaeb6db/attachment.html>