[Nut-upsdev] Embedding man pages in driver source code

[Stuart D. Gathman]

On Fri, 4 Sep 2009, Arnaud Quette wrote:

> while I clearly see the advantage of moving manpages to AsciiDoc (allow to
> generate html... output), I still don't much see the one of embedding it
> with the code.
>
> perhaps you, as the one who has practiced it, can shed my light.
> I'd also like to hear from Arjen.

I was introduced to inline docs with Javadoc, and found them so much
easier to maintain compared with separate files, that I now use Doxygen
for inline docs in my Python and C/C++ code.  

That experience is for API documentation.  For man pages, which do
not correspond directly to any code, it is not so clear cut.  For the special
case of nut drivers, however, I think having the man page info as inline
comments is helpful.  The nut drivers are like OO subclasses, and the
driver specific manpage portions included are like the class description.

-- 
	      Stuart D. Gathman <stuart at bmsi.com>
    Business Management Systems Inc.  Phone: 703 591-0911 Fax: 703 591-6154
"Confutatis maledictis, flammis acribus addictis" - background song for
a Microsoft sponsored "Where do you want to go from here?" commercial.