Changeset 1049


Ignore:
Timestamp:
Jul 17, 2012 5:15:35 PM (10 years ago)
Author:
cschlep
Message:

test if permissions work, minor changes to documentation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • specdomain/trunk/src/specdomain/doc/conventions.rst

    r1043 r1049  
    55
    66====================================================================
    7 Common Conventions
     7SPEC Documentation Conventions
    88====================================================================
    99
    10 There are several conventions
    11 for documenting SPEC macro source code files
    12 to help provide consistency.
    13 These are not requirements.
     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.
    1414
    1515.. index::
     
    4949.. Is it used to document Python code?
    5050
    51 Descriptive comments are used to document items that cannot contain
    52 extended comments (triple-quoted strings) such as variable declarations
    53 or *rdef* or *cdef* macro declarations.  They appear either in-line
    54 with the declaration or on the preceding line.
     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).
    5556
    56 Descriptive comment example that documents *tth*, a global variable declaration::
     57**Examples**:
     58Descriptive comment that documents *tth*, a global variable declaration::
    5759   
    5860    global tth    #: two-theta, the scattering angle
    5961
    60 Descriptive comment example that documents *ccdset_shutter*, a *rdef* declaration::
     62Descriptive comment that documents *ccdset_shutter*, a *rdef* declaration::
    6163
    6264    #: clear the ccd shutter handler
Note: See TracChangeset for help on using the changeset viewer.