[Top][All Lists]

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

Re: Doxygening Mach and Hurd

From: Michael Casadevall
Subject: Re: Doxygening Mach and Hurd
Date: Mon, 16 Jul 2007 01:00:35 -0400

Hash: SHA1

I don't believe the documentation should even list all the functions though. For instance, say you were working on the entropy driver, which doesn't have a public API; the only source of documentation would be the comments left behind. Its better to have a centralized document that lists all the internal API within mach with a small description of what it clear why they are used and how they are used.

I find that when I need to write a comment that summarizes a function, I do better when I know its going to appear on an API specification. In addition, if we're going to mandate updating the documentation, why build it from two sources, if you can document it in the comments, and then generate a page that describes each file in detail, thats less error prone, and much cleaner I find (and to also state that doxygen will cross-reference code and show each functions source code if you setup the Doxyfile that way).

On Jul 14, 2007, at 8:08 AM, Carl Fredrik Hammar wrote:


Michael Casadevall <sonicmctails@gmail.com> writes:

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.

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

Any thoughts and comments on doxygening the codebase?

Well I would prefer keeping the existing info pages up to date, since
it is also equipped to handle other documentation, such as overviews
and guides.  While comments are mostly an aid when reading code, and
should be concise and summarize the code.

My experience with javadoc is that it promotes making the comments the
primary documentation.  This tends to makes them overly long, which
makes them lousy as a code-reading aid.  The mark-up makes the problem
worse, you get torn between making the generated doc pretty and
keeping the comments easy to read.

The bottom-line is that comments and documentation serves different
purposes and therefore both are needed.

But I do agree that the current state of documentation is pretty
dismal.  I would argue that the proper solution is to fix it and
enforce a policy that documentation should be updated whenever the
code is updated.


Version: GnuPG v1.4.6 (Darwin)


reply via email to

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