From 1c4ae6d18cb1b1300856b9eb2923cb745277f47b Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 6 Sep 2011 19:25:47 -0400 Subject: 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. --- source/libmaple/coding-standard.rst | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) (limited to 'source/libmaple') 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 `_ for it in the + `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 + `_). + + 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 + `_. 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 `_ + pages). - **For libmaple proper**, the convention is to document any user-facing function at the point where it is defined. In -- cgit v1.2.3