Re: Doxygening Mach and Hurd

[Carl Fredrik Hammar]

Michael Casadevall <sonicmctails@gmail.com> writes:
> 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.

You contradict yourself here, the central listing of the internal API
/is/ documentation and does indeed list all the functions.

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

The documentation and the comment are usually similar enough that one
can simply copy it from one to the other with only minor changes.  So
the comment can indirectly appear on the 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

As I stated in my previous mail, documentation needs overviews as well
as the specifics, so documentation differs from comments.  That
obviously applies to internal documentation as well.

You can still use doxygen if you find it useful.  Since it's
automatic, there isn't any reason to can't use it yourself as a tool
to help you get an overview.

Cheers,
  Fredrik