From: Josh Durgin <josh.durgin@dreamhost.com>
To: ceph-devel@vger.kernel.org
Subject: Re: Code Documentation Conventions
Date: Fri, 16 Dec 2011 13:39:51 -0800 [thread overview]
Message-ID: <4EEBBAA7.8010000@dreamhost.com> (raw)
In-Reply-To: <4EEBAF78.8010605@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.
next prev parent reply other threads:[~2011-12-16 21:39 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-12-16 20:52 Code Documentation Conventions Josh Durgin
2011-12-16 21:39 ` Josh Durgin [this message]
2011-12-19 18:08 ` Tommi Virtanen
2011-12-19 18:13 ` Gregory Farnum
2011-12-19 18:34 ` Tommi Virtanen
2011-12-19 23:26 ` Sage Weil
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4EEBBAA7.8010000@dreamhost.com \
--to=josh.durgin@dreamhost.com \
--cc=ceph-devel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox