Re: Doxygening Mach and Hurd

[Carl Fredrik Hammar]

Hello!

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