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

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

test if permissions work, minor changes to documentation

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision URL Header
File size: 3.5 KB
Line 
1.. $Id: conventions.rst 1049 2012-07-17 22:15:35Z 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
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 a new construct which can be used to document items
52that cannot contain extended comments (triple-quoted strings) themselves,
53such as variable declarations or *rdef* or *cdef* macro declarations.
54They appear either as comments in the same line after the declaration (in-line)
55or as a comment-only line immediately preceding the declaration (one-liner).
56
57**Examples**:
58Descriptive comment that documents *tth*, a global variable declaration::
59   
60    global tth    #: two-theta, the scattering angle
61
62Descriptive comment that documents *ccdset_shutter*, a *rdef* declaration::
63
64    #: clear the ccd shutter handler
65    rdef ccdset_shutter ''
66
67.. spec:global:: tth    #: two-theta, the scattering angle
68
69
70
71
72.. index:: ! hidden objects
73        pair:   SPEC conventions; hidden objects
74
75hidden objects
76----------------
77
78*Hidden* objects begin with at least one underline character,
79such as ``_hidden``.  This includes macros and variables.
80These should be optional in the documentation.
81
82*Anonymous* objects begin with at least two underline characters,
83such as ``___anon``.  This includes macros and variables.
84These should not be documented unless specifically requested and
85only then if hidden objects are documented.
86
87undeclared variables
88---------------------
89
90Undeclared variables (those with no formal global, local, constant,
91or array declaration) will not be documented.  At least for now.
92
93parameter descriptions
94----------------------------
95
96Use the same syntax as parameter declarations for Python modules. 
97Here is an example SPEC macro with reST markup::
98
99        def my_comment '{
100            """
101            Make a comment
102           
103            **usage**: ``my_comment "AR aligned to 15.14063 degrees"``
104           
105            :param str text: message to be printed
106            """
107            qcomment "%s" $1
108        }'
109
110which documentation looks like this:
111
112.. spec:def:: my_comment text
113           
114            Make a comment
115           
116            **usage**: ``my_comment "AR aligned to 15.14063 degrees"``
117           
118            :param str text: message to be printed
Note: See TracBrowser for help on using the repository browser.