On 2005-05-24, Matthew Mondor <mm_lists@pulsar-zone.net> wrote:
> On Sat, 21 May 2005 14:10:03 +0000
> "Julio M. Merino Vidal" <jmmv84@gmail.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 <rpaulo@netbsd-pt.org>