Subject: Re: Doxygen generated documentation
To: Julio M. Merino Vidal <firstname.lastname@example.org>
From: Bill Studenmund <email@example.com>
Date: 05/23/2005 10:43:41
Content-Type: text/plain; charset=us-ascii
On Sat, May 21, 2005 at 02:10:03PM +0000, Julio M. Merino Vidal wrote:
> 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 =
> > 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.
I have not written comments for Doxygen, so it could be that once I do=20
I'll hate them. I'm installing it now so I can figure out. :-)
But one idea for including documentation as an auto-gen from the code is
that programmers are much more likely to update comments in the code when
they change it than update man pages. While I agree we want to update man=
pages, I think something that works off of comments in the code is better=
My off-the-cuff thought is that both man pages and what I've seen so far=20
in this thread will help document the kernel. I think they will serve=20
different purposes, and do different parts of the job well. From what I've=
seen on the web pages, Doxygen won't replace man pages and man pages don't=
easily do what Doxygen seems to do. It strikes me like the difference=20
between text and figures in a text book; a good text needs both.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (NetBSD)
-----END PGP SIGNATURE-----