At Fri, 13 Jul 2007 16:18:36 -0400 (EDT), Michael Casadevall <[EMAIL PROTECTED]> 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 _______________________________________________ Bug-hurd mailing list Bug-hurd@gnu.org http://lists.gnu.org/mailman/listinfo/bug-hurd
