Re: Code Documentation Conventions

[Josh Durgin <josh.durgin@dreamhost.com>]

On 12/16/2011 12:52 PM, Josh Durgin wrote:
> I've been documenting the librados C api, and would like to get some
> feedback on the format being used. For each function, the format is
> generally:
>
> /**
> * Short description
> *
> * Detailed description when necessary
> *
> * preconditons, postconditions, warnings, bugs or other notes
> *
> * parameter reference
> * return value (if non-void)
> */
>
> Below is some sample documentation. The markup is doxygen, although
> I've had to avoid some directives since breathe (sphinx plugin for
> reading doxygen output) removes contents it doesn't understand.

You can see the sphinx ouptut at:
http://www.joshd.dreamhosters.com/api/librados/#project0librados_8h_1a280e071e73202dca849472814a585717

The function reference all comes from doxygen's processing of 
src/include/rados/librados.h, and the code examples (which I haven't 
changed yet) are from doc/api/librados.rst. In general, I think we 
should document functions in header files and only put code examples or 
larger usage guides outside the code.

I've been focused on making the content correct, so I haven't customized 
the sphinx or doxygen configuration at all. There are lots of things we 
could improve about the output. Also I just noticed breathe is ignoring 
doxygen lists.