source: specdomain/trunk/src/specdomain/doc/conventions.rst

Last change on this file was 1088, checked in by cschlep, 10 years ago

edited style guide

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 7.5 KB
Line 
1.. $Id: conventions.rst 1088 2012-08-24 23:16:10Z jemian $
2
3.. index::  ! SPEC conventions
4        see: conventions; SPEC conventions
5
6===============================================================================
7SPEC Documentation Conventions
8===============================================================================
9
10This document lays out several conventions for documenting SPEC
11macro source code files. The aim of these conventions is to to help provide
12consistency for the "look and feel" of the resulting documentation. However,
13these conventions are by no means strict requirements.
14
15.. index:: 
16        pair:   SPEC conventions; extended comments
17
18.. _convention for extended comment:
19
20Documentation in comment blocks
21===============================
22
23Inline source documentation resides inside comment blocks within the SPEC
24macro files. It is important to note, however, that not every comment in the
25source code is part of the documentation. Rather, the comments containing the
26documentation need to be placed in a certain context, depending on the scope of
27the documentations. In analogy to the python language, we will refer to these
28documentation comments as *docstrings*, even though there are some differences
29concerning how they are implemented.
30
31Comments in SPEC
32----------------
33
34There are two ways to mark a comment in SPEC. The usual identifier is
35the ``#``-sign preceding a comment::
36
37  # This is a single comment line
38 
39  my_val = 2.0  # This is an in-line comment
40
41A less well-known identifier to designate multi-line comments is the
42use of triple double-quotes (``"""``), which were introduced specifically with
43docstrings in mind [#spec_docstring]_::
44
45  """
46  This is an extended comment in SPEC.
47 
48  Note that it can span multiple lines and contain several paragraphs.
49 
50  """
51 
52.. warning::
53
54    Do not use the single-quote characters (``'``) to mark an extended comment!
55        In the Python language, a docstring can be included either in triple
56        double-quotes (``"""``) or in triple single-quotes (``'''``).
57        But, **unlike Python**, SPEC does not recognize single quotes
58        to mark extended comments. Only use the double quote character for SPEC
59        files.
60
61
62Extended comments
63-----------------
64
65The first extended comment in a "section" should contain the docstring. Any
66other extended comments will be ignored and not processed during the
67documentation creation (this setting could be changed with an optional switch.)
68In this context, a *section* refers to a particular "code object", which might
69be the global scope of a .mac file or a macro definition block, for example.
70
71The first paragraph of the docstring should be a concise summary line, followed
72by a blank line. This summary will be parsed in a special way to be included as
73a description of the code object in summary tables, indices, etc. If the first
74paragraph starts with a colon (``:``), no summary text will be assumed.
75
76Following the summary, a more elaborate description of the code object may be
77given.
78
79For macro definitions (``def, rdef``), the docstring should immediately follow
80the declaration line and be indented to the same level as the code contained
81within the definition. It is also recommended to insert a blank line between
82the last paragraph in a multi-line docstring and its closing quotes, placing
83the closing quotes on a line by themselves::
84
85  def my_macro_def '{
86    """
87    This is the summary line.
88   
89    And here is some more elaborate discussion of the functionality, which may
90    again extend over several lines or paragraphs, and contain all the required
91    reST and Sphinx markup.
92   
93    """
94   
95    my_var = 1.0
96   
97    # do some more stuff...
98   
99  }'
100
101Finally, it is recommended to use the extended comment syntax with
102triple-quotes only for docstrings, even though it is a valid syntax to include
103longer blocks of comments about the code itself. To avoid confusion between the
104two types of comments, non-documentation comments should be included by
105preceding each line with the ``#``-sign::
106
107  """
108  This is my docstring.
109 
110  """
111 
112  # Here, I write down some
113  # comments about how
114  # exactly my code works:
115  #
116  # Increment x by 1 for each registered photon
117
118  if(hit) x+=1
119
120.. index:: ! descriptive comments
121        pair:   SPEC conventions; descriptive comments
122
123.. _descriptive comment:
124
125
126Descriptive comments
127--------------------
128
129.. caution::  This is new convention,
130                                yet it does not violate any SPEC rules.
131                                It *is* awfully useful!
132.. Is it used to document Python code?
133
134Descriptive comments are a new construct which can be used to document items
135that cannot contain extended comments (triple-quoted strings) themselves,
136such as variable declarations or *rdef* or *cdef* macro declarations.
137(They can also be used to document one-line *def* macros!)
138They appear either as comments in the same line after the declaration (in-line)
139or as a comment-only line immediately preceding the declaration (one-liner).
140Descriptive comments are marked by a preceding ``#:``, which lets them appear
141like normal SPEC comments, but the colon triggers the parser to process the
142docstring.
143
144Like the summary lines in extended comments, these descriptive comments are
145used as descriptions in summary tables, etc.
146
147**Examples**:
148
149Descriptive comment that documents **TTH**, a global variable declaration::
150   
151    global TTH    #: two-theta, the scattering angle
152
153Descriptive comment that documents **ccdset_shutter**, an *rdef* declaration::
154
155    #: clear the ccd shutter handler
156    rdef ccdset_shutter ''
157
158Descriptive comment that documents **do_nothing()**, a *function def* declaration::
159
160    def do_nothing() ''      #: this macro does do anything
161
162
163
164.. index:: ! hidden objects
165        pair:   SPEC conventions; hidden objects
166
167
168Hidden objects
169----------------
170
171*Hidden* objects begin with at least one underline character,
172such as ``_hidden``.  This includes macros and variables.
173These should be optional in the documentation.
174
175*Anonymous* objects begin with at least two underline characters,
176such as ``___anon``.  This includes macros and variables.
177These should not be documented unless specifically requested and
178only then if hidden objects are documented.
179
180Undeclared variables
181---------------------
182
183Undeclared variables (those with no formal global, local, constant,
184or array declaration) will not be documented.  At least for now.
185
186Parameter descriptions
187----------------------------
188
189Use the same syntax as parameter declarations for Python modules. 
190Here is an example SPEC macro with reST markup::
191
192        def my_comment '{
193                """
194                Make a comment
195               
196                USAGE::
197               
198                  > my_comment "AR aligned to 15.14063 degrees"
199               
200                ARGUMENTS:
201               
202                  :param str text: message to be printed
203                 
204                """
205               
206                qcomment "%s" $1
207        }'
208
209which documentation looks like this:
210
211.. spec:def:: my_comment text x y
212           
213            Make a comment
214           
215            USAGE::
216           
217              > my_comment "AR aligned to 15.14063 degrees"``
218             
219            ARGUMENTS:
220           
221            :param str text: message to be printed
222           
223           
224            :arg float x: some number to be processed
225            :arg y: another number (without type)
226             
227            RETURNS:
228
229        :returns str comment: the comment
230
231
232.. spec:cdef:: cdef("demo_cdef_more", "spec_code", "key", flags)
233     
234     This is my punch line!
235     
236         :param str demo_cdef_more: name of chained macro
237         :param str spec_code: SPEC code to be executed (usually a single macro name)
238         :param str key: name of this part of the chained macro
239         :param flags: see **SPEC** documentation for details
240         :param str not_here: something is missing...
241         :rtype: none
242           
243           
244
245
246------------
247
248.. rubric:: Footnotes
249.. [#spec_docstring] SPEC extended comments for docstrings:
250   http://www.certif.com/spec_help/chg5_01.html
251
Note: See TracBrowser for help on using the repository browser.