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

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

refs #8, finished documenting a complete example

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