bug-hurd
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Doxygening Mach and Hurd


From: Marcus Brinkmann
Subject: Re: Doxygening Mach and Hurd
Date: Sat, 14 Jul 2007 13:09:52 +0200
User-agent: Wanderlust/2.14.0 (Africa) SEMI/1.14.6 (Maruoka) FLIM/1.14.8 (Shijō) APEL/10.6 Emacs/23.0.0 (i486-pc-linux-gnu) MULE/6.0 (HANACHIRUSATO)

At Fri, 13 Jul 2007 16:18:36 -0400 (EDT),
Michael Casadevall <sonicmctails@gmail.com> wrote:
> During my time correcting the entropy patch to meet the requirements to be 
> accepted, I noticved the coding style would make it extremely easy to doxyify 
> the codebase.

In my experience, in-source markup makes for poor source code and poor
documentation at the same time.  You are basically interleaving two
source codes for different languages and towards different ends.  The
requirements for a manual and for source code are different, and may
conflict.

> For those of you unfamilar with Doxygen, its similar
> to Javadoc and other solutions that use markup in the code
> base to generate documentation. I believe one of the bigger
> problems with mach, and especially getting new developers is
> that mach itself is fairly undocumented, especially its internals
> (the only real documentation of IPC I know if is Thomas' guide).
> I think it would be in the projects best interests if we start
> doxyifing the codebase (which is fairly easy to do; I learned
> how to use use doxygen in about five minutes the first time
> I ever used it).

But of course the problem is not the markup, but in writing good
documentation.

Documenting the internals is important, but well written source code
together with an overview manual should be more satisfying, IMO.

Thanks,
Marcus





reply via email to

[Prev in Thread] Current Thread [Next in Thread]