Subject: Re: Doxygen generated documentation
To: Julio M. Merino Vidal <jmmv84@gmail.com>
From: Jachym Holecek <freza@liberouter.org>
List: tech-kern
Date: 05/22/2005 23:33:15
Hello,

> On Sat, 2005-05-21 at 11:29 +0000, Rui Paulo wrote:
> 
> > > Rui im more than happy to help you mark up code with doxygen comments
> > 
> > That's something that must be discussed, because not everyone may want to
> > add Doxygen comments to the source. Another ideia is to add some target
> > to build.sh/Makefile to generate Doxygen documentation.
> > 
> > Doxygen comments aren't very intrusive, though.
> 
> The thing is that we already have documentation for frameworks,
> functions and data structures in manual pages; duplicating it inside
> source code is not a very good idea, as I see it.

True, plus doxygening the source makes it harder to read (too much
comments when you want to see code, too much code when you're seeking
for a comment.) At least that's my brief experience w/ Doxygen...

That said, the pages Rui generated look promising, making some
links point to HTMLized man pages instead of embedding Doxygen markup
in the C files themselves would be just about enough. No clue if
there's a simple enough way to do that automatically.

> FWIW, the existing manual pages are very good.  Check, for example,
> spl(9), mbuf(9), wscons(9), etc.

Yes, but some just aren't there (no ifnet(9), iic(9), mii(9) for
example). "The Rigth Fix" is just writing them, IMO.

	Regards,
		-- Jachym Holecek