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.

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...

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?)

Matt

-- 
Note: Please only reply on the list since other mail is blocked by default.
Private messages from your address can be allowed by first asking, however.