Changeset 1050
- Timestamp:
- Jul 17, 2012 6:53:47 PM (11 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
specdomain/trunk/src/specdomain/doc/conventions.rst
r1049 r1050 4 4 see: conventions; SPEC conventions 5 5 6 ==================================================================== 6 =============================================================================== 7 7 SPEC Documentation Conventions 8 ==================================================================== 8 =============================================================================== 9 9 10 10 This document lays out several conventions for for documenting SPEC … … 18 18 .. _convention for extended comment: 19 19 20 extended comment 20 Documentation in comment blocks 21 =============================== 22 23 Inline source documentation resides inside comment blocks within the SPEC 24 macro files. It is important to note, however, that not every comment in the 25 source code is part of the documentation. Rather, the comments containing the 26 documentation need to be placed in a certain context, depending on the scope of 27 the documentations. In analogy to the python language, we will refer to these 28 documentation comments as *docstrings*, even though there are some differences 29 concerning how they are implemented. 30 31 Comments in SPEC 32 ---------------- 33 34 There are two ways to mark a comment in SPEC. The usual identifier is 35 the ``#``-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 41 A less well-known identifier to designate multi-line comments is the 42 use of triple double-quotes (``"""``), which were introduced specifically with 43 docstrings 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 62 Extended comments 21 63 ----------------- 22 64 23 Only the first extended comment in a "section" should be documented. 24 (This setting could be changed with an optional switch.) 25 26 A *section* might be the global scope of a .mac file or a macro definition block. 27 28 As much as possible, use the python documentation style (that is, 29 first comment is module documentation, first comment inside 30 macro definition is the macro documentation). 31 32 The first paragraph should be very short, preferably one line. 33 It is assumed to be the summary. 34 If the first paragraph starts with a ":", no summary text will be assumed. 35 36 65 The first extended comment in a "section" should contain the docstring. Any 66 other extended comments will be ignored and not processed during the 67 documentation creation (this setting could be changed with an optional switch.) 68 In this context, a *section* refers to a particular "code object", which might 69 be the global scope of a .mac file or a macro definition block, for example. 70 71 The first paragraph of the docstring should be a concise summary line, followed 72 by a blank line. This summary will be parsed in a special way to be included as 73 a description of the code object in summary tables, indices, etc. If the first 74 paragraph starts with a colon (``:``), no summary text will be assumed. 75 76 Following the summary, a more elaborate description of the code object may be 77 given. 78 79 For macro definitions (``def, rdef``), the docstring should immediately follow 80 the declaration line and be indented to the same level as the code contained 81 within the definition. It is also recommended to insert a blank line between 82 the last paragraph in a multi-line docstring and its closing quotes, placing 83 the 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 101 Finally, it is recommended to use the extended comment syntax with 102 triple-quotes only for docstrings, even though it is a valid syntax to include 103 longer blocks of comments about the code itself. To avoid confusion between the 104 two types of comments, non-documentation comments should be included by 105 preceding 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 37 119 38 120 .. index:: ! descriptive comments … … 41 123 .. _descriptive comment: 42 124 43 descriptive comment 44 --------------------- 125 126 Descriptive comments 127 -------------------- 45 128 46 129 .. caution:: This is not a confirmed convention yet, … … 54 137 They appear either as comments in the same line after the declaration (in-line) 55 138 or as a comment-only line immediately preceding the declaration (one-liner). 139 Descriptive comments are marked by a preceding ``#:``, which lets them appear 140 like normal SPEC comments, but the colon triggers the parser to process the 141 docstring. 142 143 Like the summary lines in exteded docstrings, these descriptive comments are 144 used as descriptions in summary tables, etc. 56 145 57 146 **Examples**: 58 Descriptive comment that documents *tth*, a global variable declaration:: 59 60 global tth #: two-theta, the scattering angle 61 62 Descriptive comment that documents *ccdset_shutter*, a *rdef* declaration:: 147 148 Descriptive comment that documents **TTH**, a global variable declaration:: 149 150 global TTH #: two-theta, the scattering angle 151 152 Descriptive comment that documents **ccdset_shutter**, an *rdef* declaration:: 63 153 64 154 #: clear the ccd shutter handler 65 155 rdef ccdset_shutter '' 66 156 67 .. spec:global:: tth #: two-theta, the scattering angle 68 157 .. spec:global:: TTH #: two-theta, the scattering angle 69 158 70 159 … … 73 162 pair: SPEC conventions; hidden objects 74 163 75 hidden objects 164 165 Hidden objects 76 166 ---------------- 77 167 … … 85 175 only then if hidden objects are documented. 86 176 87 undeclared variables177 Undeclared variables 88 178 --------------------- 89 179 … … 91 181 or array declaration) will not be documented. At least for now. 92 182 93 parameter descriptions183 Parameter descriptions 94 184 ---------------------------- 95 185 … … 117 207 118 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 TracChangeset
for help on using the changeset viewer.
