diff options
author | Josh Durgin <josh.durgin@dreamhost.com> | 2011-12-29 15:57:33 -0800 |
---|---|---|
committer | Josh Durgin <josh.durgin@dreamhost.com> | 2012-01-09 19:10:10 -0800 |
commit | dd31ff2e5cdf9dde2b010315ef8f878ef53ddf9c (patch) | |
tree | e122c25b6290866e9bb22ce4b03d9b4604a9c07f /doc/dev | |
parent | 0e19062c8297fab2d79852dc8a62935ae9d6bb3c (diff) | |
download | ceph-dd31ff2e5cdf9dde2b010315ef8f878ef53ddf9c.tar.gz |
doc: add short section on documenting code
Signed-off-by: Josh Durgin <josh.durgin@dreamhost.com>
Diffstat (limited to 'doc/dev')
-rw-r--r-- | doc/dev/documenting.rst | 30 |
1 files changed, 30 insertions, 0 deletions
diff --git a/doc/dev/documenting.rst b/doc/dev/documenting.rst index 870703f787f..1135f6c083c 100644 --- a/doc/dev/documenting.rst +++ b/doc/dev/documenting.rst @@ -2,6 +2,36 @@ Documenting Ceph ================== +Code Documentation +================== + +C and C++ can be documented with Doxygen_, using the subset of Doxygen +markup supported by Asphyxiate_. + +.. _Doxygen: http://www.stack.nl/~dimitri/doxygen/ +.. _Asphyxiate: https://github.com/NewDreamNetwork/asphyxiate + +The general format for function documentation is:: + + /** + * Short description + * + * Detailed description when necessary + * + * preconditons, postconditions, warnings, bugs or other notes + * + * parameter reference + * return value (if non-void) + */ + +This should be in the header where the function is declared, and +functions should be grouped into logical categories. The `librados C +API`_ provides a complete example. It is pulled into Sphinx by +`librados.rst`_, which is rendered at :doc:`/api/librados`. + +.. _`librados C API`: https://github.com/NewDreamNetwork/ceph/blob/master/src/include/rados/librados.h +.. _`librados.rst`: https://raw.github.com/NewDreamNetwork/ceph/master/doc/api/librados.rst + Drawing diagrams ================ |