Changeset 1050

Jul 17, 2012 6:53:47 PM (11 years ago)

modifications and improvements in the documentation

1 edited


  • specdomain/trunk/src/specdomain/doc/conventions.rst

    r1049 r1050  
    44        see: conventions; SPEC conventions
    6 ====================================================================
    77SPEC Documentation Conventions
    8 ====================================================================
    1010This document lays out several conventions for for documenting SPEC
    1818.. _convention for extended comment:
    20 extended comment
     20Documentation in comment blocks
     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.
     31Comments in SPEC
     34There are two ways to mark a comment in SPEC. The usual identifier is
     35the ``#``-sign preceding a comment::
     37  # This is a single comment line
     39  my_val = 2.0  # This is an in-line comment
     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]_::
     45  """
     46  This is an extended comment in SPEC.
     48  Note that it can span multiple lines and contain several paragraphs.
     50  """
     52.. warning::
     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.
     62Extended comments
    23 Only the first extended comment in a "section" should be documented.
    24 (This setting could be changed with an optional switch.)
    26 A *section* might be the global scope of a .mac file or a macro definition block.
    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).
    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.
     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.
     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.
     76Following the summary, a more elaborate description of the code object may be
     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::
     85  def my_macro_def '{
     86    """
     87    This is the summary line.
     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.
     93    """
     95    my_var = 1.0
     97    # do some more stuff...
     99  }'
     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::
     107  """
     108  This is my docstring.
     110  """
     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
     118  if(hit) x+=1
    38120.. index:: ! descriptive comments
    41123.. _descriptive comment:
    43 descriptive comment
    44 ---------------------
     126Descriptive comments
    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
     143Like the summary lines in exteded docstrings, these descriptive comments are
     144used as descriptions in summary tables, etc.
    58 Descriptive comment that documents *tth*, a global variable declaration::
    60     global tth    #: two-theta, the scattering angle
    62 Descriptive comment that documents *ccdset_shutter*, a *rdef* declaration::
     148Descriptive comment that documents **TTH**, a global variable declaration::
     150    global TTH    #: two-theta, the scattering angle
     152Descriptive comment that documents **ccdset_shutter**, an *rdef* declaration::
    64154    #: clear the ccd shutter handler
    65155    rdef ccdset_shutter ''
    67 .. spec:global:: tth    #: two-theta, the scattering angle
     157.. spec:global:: TTH    #: two-theta, the scattering angle
    73162        pair:   SPEC conventions; hidden objects
    75 hidden objects
     165Hidden objects
    85175only then if hidden objects are documented.
    87 undeclared variables
     177Undeclared variables
    91181or array declaration) will not be documented.  At least for now.
    93 parameter descriptions
     183Parameter descriptions
    118208            :param str text: message to be printed
     213.. rubric:: Footnotes
     214.. [#spec_docstring] SPEC extended comments for docstrings:
Note: See TracChangeset for help on using the changeset viewer.