-----BEGIN PGP SIGNED MESSAGE-----
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).
Michael
On Jul 14, 2007, at 8:08 AM, Carl Fredrik Hammar wrote:
Hello!
Michael Casadevall <[EMAIL PROTECTED]> 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?
Michael
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.
Cheers,
Fredrik
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (Darwin)
iD8DBQFGmvt0V/FBeJ6jsZQRAsw9AJ9BRIdp9z3NgcGvjxI67WqF49xcZwCbB4D6
0lz7U+eAqUcr8F/6/DGkBlA=
=0eEI
-----END PGP SIGNATURE-----
_______________________________________________
Bug-hurd mailing list
Bug-hurd@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-hurd
