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.
--
To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
