2012/10/29 <[email protected]> > 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
_______________________________________________ Nut-upsdev mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/nut-upsdev
