aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-09-06 19:25:47 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2011-09-06 20:02:27 -0400
commit1c4ae6d18cb1b1300856b9eb2923cb745277f47b (patch)
treefcba632329ff89878f88cac4d7b3b5548a8e2c21
parent0cf0959b54c05d9a058304331c3326b579c9b2d9 (diff)
downloadlibrambutan-1c4ae6d18cb1b1300856b9eb2923cb745277f47b.tar.gz
librambutan-1c4ae6d18cb1b1300856b9eb2923cb745277f47b.zip
coding-standard: Updates and clarifications.
We got rid of the Windows newlines a while ago, so nuke the "exceptions" clause in the Unix newlines requirement. Teach the Doxygen -> Breathe information about the leaflabs-docs repo and the wiki. Also provide more links to further sources of information on what to do.
-rw-r--r--source/libmaple/coding-standard.rst37
1 files changed, 21 insertions, 16 deletions
diff --git a/source/libmaple/coding-standard.rst b/source/libmaple/coding-standard.rst
index d22f12e..079329b 100644
--- a/source/libmaple/coding-standard.rst
+++ b/source/libmaple/coding-standard.rst
@@ -60,8 +60,7 @@ whitespace at save time.
- 4 space indents (set in ``.dir-locals.el``).
-- Unix newlines. Some exceptions are currently grandfathered in; these
- will go away in time.
+- Unix newlines.
- No tab characters (set in ``.dir-locals.el``).
@@ -319,19 +318,24 @@ Documentation
by reading ST RM0008.
- Doxygen comments generally only belong on types, functions,
- etc. that are part of the public user-facing API. This generally
- means that if there's ReST documentation for it under libmaple's
- ``docs/source/``, it needs Doxygen comments, and that ReST should
- use Breathe to pull that Doxygen comment out. (For more information
- on this, see libmaple file ``docs/README``).
-
- There are some exceptions to this rule since Breathe isn't totally
- mature yet and Sphinx's C++ domain is still in flux. In these
- cases, document the code "manually" in ReST.
-
- This should be avoided if at all possible, since it creates a
- maintenance burden of documenting things in two places at once, and
- makes it easier for documentation to go stale.
+ etc. that are part of the public user-facing API.
+
+ This essentially means that if what you're writing is going to be
+ documented under http://leaflabs.com/docs/ (i.e., if there's `Sphinx
+ documentation <http://sphinx.pocoo.org/>`_ for it in the
+ `leaflabs-docs <https://github.com/leaflabs/leaflabs-docs>`_
+ repository), then you need to write Doxygen comments. Further,
+ those Sphinx docs should use Breathe to pull the Doxygen out. (For
+ more information on this, see the `leaflabs-docs README
+ <https://raw.github.com/leaflabs/leaflabs-docs/master/README>`_).
+
+ Because Breathe isn't totally mature yet, you won't always be able
+ to do this. In these cases, document the code "manually" using the
+ Sphinx `C and C++ domains
+ <http://sphinx.pocoo.org/domains.html#the-c-domain>`_. This should
+ be avoided if at all possible, since it creates a maintenance burden
+ of documenting things in two places at once, and makes it easier for
+ documentation to go stale.
If you do have to document something manually, put a comment in the
source file informing future maintainers about it, so they'll pay
@@ -345,7 +349,8 @@ Documentation
This lets us keep the source files relatively free of "introductory"
material, while allowing new readers a convenient starting point.
These longer-form notes also have a habit of turning into official,
- user-facing documentation.
+ user-facing documentation (or `wiki <http://wiki.leaflabs.com>`_
+ pages).
- **For libmaple proper**, the convention is to document any
user-facing function at the point where it is defined. In