Changeset 1050


Ignore:
Timestamp:
Jul 17, 2012 6:53:47 PM (10 years ago)
Author:
cschlep
Message:

modifications and improvements in the documentation

File:
1 edited

Legend:

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

    r1049 r1050  
    44        see: conventions; SPEC conventions
    55
    6 ====================================================================
     6===============================================================================
    77SPEC Documentation Conventions
    8 ====================================================================
     8===============================================================================
    99
    1010This document lays out several conventions for for documenting SPEC
     
    1818.. _convention for extended comment:
    1919
    20 extended comment
     20Documentation in comment blocks
     21===============================
     22
     23Inline source documentation resides inside comment blocks within the SPEC
     24macro files. It is important to note, however, that not every comment in the
     25source code is part of the documentation. Rather, the comments containing the
     26documentation need to be placed in a certain context, depending on the scope of
     27the documentations. In analogy to the python language, we will refer to these
     28documentation comments as *docstrings*, even though there are some differences
     29concerning how they are implemented.
     30
     31Comments in SPEC
     32----------------
     33
     34There are two ways to mark a comment in SPEC. The usual identifier is
     35the ``#``-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
     41A less well-known identifier to designate multi-line comments is the
     42use of triple double-quotes (``"""``), which were introduced specifically with
     43docstrings 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
     62Extended comments
    2163-----------------
    2264
    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 
     65The first extended comment in a "section" should contain the docstring. Any
     66other extended comments will be ignored and not processed during the
     67documentation creation (this setting could be changed with an optional switch.)
     68In this context, a *section* refers to a particular "code object", which might
     69be the global scope of a .mac file or a macro definition block, for example.
     70
     71The first paragraph of the docstring should be a concise summary line, followed
     72by a blank line. This summary will be parsed in a special way to be included as
     73a description of the code object in summary tables, indices, etc. If the first
     74paragraph starts with a colon (``:``), no summary text will be assumed.
     75
     76Following the summary, a more elaborate description of the code object may be
     77given.
     78
     79For macro definitions (``def, rdef``), the docstring should immediately follow
     80the declaration line and be indented to the same level as the code contained
     81within the definition. It is also recommended to insert a blank line between
     82the last paragraph in a multi-line docstring and its closing quotes, placing
     83the 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
     101Finally, it is recommended to use the extended comment syntax with
     102triple-quotes only for docstrings, even though it is a valid syntax to include
     103longer blocks of comments about the code itself. To avoid confusion between the
     104two types of comments, non-documentation comments should be included by
     105preceding 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
    37119
    38120.. index:: ! descriptive comments
     
    41123.. _descriptive comment:
    42124
    43 descriptive comment
    44 ---------------------
     125
     126Descriptive comments
     127--------------------
    45128
    46129.. caution::  This is not a confirmed convention yet,
     
    54137They appear either as comments in the same line after the declaration (in-line)
    55138or as a comment-only line immediately preceding the declaration (one-liner).
     139Descriptive comments are marked by a preceding ``#:``, which lets them appear
     140like normal SPEC comments, but the colon triggers the parser to process the
     141docstring.
     142
     143Like the summary lines in exteded docstrings, these descriptive comments are
     144used as descriptions in summary tables, etc.
    56145
    57146**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
     148Descriptive comment that documents **TTH**, a global variable declaration::
     149   
     150    global TTH    #: two-theta, the scattering angle
     151
     152Descriptive comment that documents **ccdset_shutter**, an *rdef* declaration::
    63153
    64154    #: clear the ccd shutter handler
    65155    rdef ccdset_shutter ''
    66156
    67 .. spec:global:: tth    #: two-theta, the scattering angle
    68 
     157.. spec:global:: TTH    #: two-theta, the scattering angle
    69158
    70159
     
    73162        pair:   SPEC conventions; hidden objects
    74163
    75 hidden objects
     164
     165Hidden objects
    76166----------------
    77167
     
    85175only then if hidden objects are documented.
    86176
    87 undeclared variables
     177Undeclared variables
    88178---------------------
    89179
     
    91181or array declaration) will not be documented.  At least for now.
    92182
    93 parameter descriptions
     183Parameter descriptions
    94184----------------------------
    95185
     
    117207           
    118208            :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.