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

Last change on this file since 1028 was 1028, checked in by jemian, 10 years ago

refs #8: finish the documentation

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 3.2 KB
Line 
1.. $Id: conventions.rst 1028 2012-07-16 06:06:58Z jemian $
2
3.. index::  ! SPEC conventions
4        see: conventions; SPEC conventions
5
6====================================================================
7Common Conventions
8====================================================================
9
10There are several conventions
11for documenting SPEC macro source code files
12to help provide consistency.
13These are not requirements.
14
15.. index:: 
16        pair:   SPEC conventions; extended comments
17
18.. _convention for extended comment:
19
20extended comment
21-----------------
22
23Only the first extended comment in a "section" should be documented.
24(This setting could be changed with an optional switch.)
25
26A *section* might be the global scope of a .mac file or a macro definition block.
27
28As much as possible, use the python documentation style (that is,
29first comment is module documentation, first comment inside
30macro definition is the macro documentation).
31
32The first paragraph should be very short, preferably one line.
33It is assumed to be the summary.
34If the first paragraph starts with a ":", no summary text will be assumed.
35
36
37
38.. index:: ! descriptive comments
39        pair:   SPEC conventions; descriptive comments
40
41.. _descriptive comment:
42
43descriptive comment
44---------------------
45
46.. caution::  This is not a confirmed convention yet,
47                                but it does not violate any SPEC rules.
48                                It *is* awfully useful!
49.. Is it used to document Python code?
50
51Descriptive comments are used to document items that cannot contain
52extended comments (triple-quoted strings) such as variable declarations
53or *rdef* or *cdef* macro declarations.  They appear either in-line
54with the declaration or on the preceding line.
55
56Descriptive comment example that documents *tth*, a global variable declaration::
57   
58    global tth    #: two-theta, the scattering angle
59
60Descriptive comment example that documents *ccdset_shutter*, a *rdef* declaration::
61
62    #: clear the ccd shutter handler
63    rdef ccdset_shutter ''
64
65.. spec:global:: tth    #: two-theta, the scattering angle
66
67
68
69
70.. index:: ! hidden objects
71        pair:   SPEC conventions; hidden objects
72
73hidden objects
74----------------
75
76*Hidden* objects begin with at least one underline character,
77such as ``_hidden``.  This includes macros and variables.
78These should be optional in the documentation.
79
80*Anonymous* objects begin with at least two underline characters,
81such as ``___anon``.  This includes macros and variables.
82These should not be documented unless specifically requested and
83only then if hidden objects are documented.
84
85undeclared variables
86---------------------
87
88Undeclared variables (those with no formal global, local, constant,
89or array declaration) will not be documented.  At least for now.
90
91parameter descriptions
92----------------------------
93
94Use the same syntax as parameter declarations for Python modules. 
95Here is an example SPEC macro with reST markup::
96
97        def my_comment '{
98            '''
99            Make a comment
100           
101            **usage**: ``my_comment "AR aligned to 15.14063 degrees"``
102           
103            :param str text: message to be printed
104            '''
105            qcomment "%s" $1
106        }'
107
108which documentation looks like this:
109
110.. spec:def:: my_comment text
111           
112            Make a comment
113           
114            **usage**: ``my_comment "AR aligned to 15.14063 degrees"``
115           
116            :param str text: message to be printed
Note: See TracBrowser for help on using the repository browser.