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

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

modifications and improvements in the documentation

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 6.8 KB
Line 
1.. $Id: conventions.rst 1050 2012-07-17 23:53:47Z cschlep $
2
3.. index::  ! SPEC conventions
4        see: conventions; SPEC conventions
5
6===============================================================================
7SPEC Documentation Conventions
8===============================================================================
9
10This document lays out several conventions for 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    rst 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 not a confirmed convention yet,
130                                but 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.
137They appear either as comments in the same line after the declaration (in-line)
138or as a comment-only line immediately preceding the declaration (one-liner).
139Descriptive comments are marked by a preceding ``#:``, which lets them appear
140like normal SPEC comments, but the colon triggers the parser to process the
141docstring.
142
143Like the summary lines in exteded docstrings, these descriptive comments are
144used as descriptions in summary tables, etc.
145
146**Examples**:
147
148Descriptive comment that documents **TTH**, a global variable declaration::
149   
150    global TTH    #: two-theta, the scattering angle
151
152Descriptive comment that documents **ccdset_shutter**, an *rdef* declaration::
153
154    #: clear the ccd shutter handler
155    rdef ccdset_shutter ''
156
157.. spec:global:: TTH    #: two-theta, the scattering angle
158
159
160
161.. index:: ! hidden objects
162        pair:   SPEC conventions; hidden objects
163
164
165Hidden objects
166----------------
167
168*Hidden* objects begin with at least one underline character,
169such as ``_hidden``.  This includes macros and variables.
170These should be optional in the documentation.
171
172*Anonymous* objects begin with at least two underline characters,
173such as ``___anon``.  This includes macros and variables.
174These should not be documented unless specifically requested and
175only then if hidden objects are documented.
176
177Undeclared variables
178---------------------
179
180Undeclared variables (those with no formal global, local, constant,
181or array declaration) will not be documented.  At least for now.
182
183Parameter descriptions
184----------------------------
185
186Use the same syntax as parameter declarations for Python modules. 
187Here is an example SPEC macro with reST markup::
188
189        def my_comment '{
190            """
191            Make a comment
192           
193            **usage**: ``my_comment "AR aligned to 15.14063 degrees"``
194           
195            :param str text: message to be printed
196            """
197            qcomment "%s" $1
198        }'
199
200which documentation looks like this:
201
202.. spec:def:: my_comment text
203           
204            Make a comment
205           
206            **usage**: ``my_comment "AR aligned to 15.14063 degrees"``
207           
208            :param str text: message to be printed
209
210
211------------
212
213.. rubric:: Footnotes
214.. [#spec_docstring] SPEC extended comments for docstrings:
215   http://www.certif.com/spec_help/chg5_01.html
216
Note: See TracBrowser for help on using the repository browser.