Subject: Re: Doxygen generated documentation
To: None <firstname.lastname@example.org>
From: Rui Paulo <email@example.com>
Date: 05/24/2005 11:55:31
On 2005-05-24, Matthew Mondor <firstname.lastname@example.org> wrote:
> On Sat, 21 May 2005 14:10:03 +0000
> "Julio M. Merino Vidal" <email@example.com> 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 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.
>> FWIW, the existing manual pages are very good. Check, for example,
>> spl(9), mbuf(9), wscons(9), etc.
> Often, when reading source-based generated reference documentation such
> as javadocs (which doxigen reminds me of somewhat), either there were
> way too much comments in the code, or that the framework scope and
> documentation was messy, because the documentation was centered around
> functions (often repetitive, although also generally lacking a bird's
> eye view of the framework). Manual pages are written by humans to
> represent a common framework to solve a problem, and are generally
> better at this.
I never meant to replace man pages. Man pages *are* useful and shouldn't go
away. How often they are updated it's another question, though.
> Not saying that graphs like what Rui showed aren't nice or useful
> though, but I don't think we should migrate from man pages to doxigen
> generated docs, or bloat the NetBSD code with extended documentation...
I agree with Bill's point: both are useful and if we have call graphs
that help understanding a framework, I think it's better than nothing.
> However, it's common (because I saw this often) for frameworks to evolve
> without their man pages being updated consequently. The few times I
> complained to authors about this, I was blatently told to fill a PR
> about it. Is there a better solution to this? Is mdoc considered a
> burden for most developpers? I guess it all has to be considered at
> this point when talking about documentation... (also, netbsd-docs
> mailing list might be a good place for a thread about this, prehaps?)
Since I Doxygen'ed kernel frameworks I though people reading tech-kern@
would be interested too (that's the reason of the cross-post).
Rui Paulo <firstname.lastname@example.org>