Documenting SPEC Code

Documenting SPEC File Directories

.. autospecdir:: path
Param str path:path (absolute or relative to the .rst file) to an accessible directory with SPEC macro files 
.. autospecdir:: /home/user/spec.d/macros

Note

options planned for future versions:

  • document all subdirectories of path
  • match files by a pattern (? glob v. re ?)

Documenting SPEC Files

.. autospecmacro:: filename
Param str filename:
 name (with optional path) of the SPEC macro file. The path component can be relative or absolute. If relative, the path is relative to the .rst file.

Document the contents of a SPEC macro source code file, including extended comments, def, rdef, and cdef macro declarations and changes, and local, global, and constant variable declarations.

.. autospecmacro:: sixc.mac

Note

options planned for future versions:

  • standard documentation pattern
  • include all extended comments
  • ignore hidden objects [1]
  • ignore anonymous objects [2]

SPEC Extended Comments

Do not use the single-quote character to mark an extended comment.

In the Python language, a triple-quoted string is known as a docstring. But, unlike Python, SPEC does not recognize single quotes to mark extended comments. Only use the double quote character for SPEC files.

Since 2002, SPEC has provided an extended comment block. [3] Such a block begins and ends with three double-quotes, such as:

"""This is an extended comment"""

Here, the extended comment block should be formatted according to the conventions of restructured text [4]. There is also a recommended convention for using extended comments in SPEC macro files.

Describing SPEC objects

The following directives refer to objects in SPEC macro source code files and create index entries and identifiers:

.. spec:def::

Declare the name of a SPEC def macro.

ReST code Displays like 
.. spec:def:: demo_def
demo_def
.. spec:rdef::

Declare the name of a SPEC rdef run-time-defined macro.

ReST code Displays like 
.. spec:rdef:: demo_rdef
demo_rdef
.. spec:cdef::

Declare the name of a SPEC cdef chained macro.

ReST code Displays like 
.. spec:cdef:: cdef("demo_cdef")
demo_cdef['<<< cdef argument list not handled yet >>>']

More elaborate example showing how to call a chained macro and also describe the arguments:

.. spec:cdef:: cdef("demo_cdef_more", "spec_code", "key", flags)

   :param str demo_cdef_more: name of chained macro
   :param str spec_code: SPEC code to be executed (usually a single macro name)
   :param str key: name of this part of the chained macro
   :param flags: see http://www.certif.com/spec_help/funcs.html
   :rtype: none

   This text is ignored (for now).

Displays like:

demo_cdef_more['<<< cdef argument list not handled yet >>>']
Parameters:
  • demo_cdef_more (str) – name of chained macro
  • spec_code (str) – SPEC code to be executed (usually a single macro name)
  • key (str) – name of this part of the chained macro
  • flags – see SPEC documentation for details
Return type:

none
.. spec:global::

Declare the name of a SPEC global variable.

ReST code Displays like 
.. spec:global:: demo_global
demo_global
.. spec:local::

Declare the name of a SPEC local variable.

ReST code Displays like 
.. spec:local:: demo_local
demo_local
.. spec:constant::

Declare the name of a SPEC constant.

ReST code Displays like 
.. spec:constant:: demo_const
demo_const

Cross-referencing SPEC objects

The following roles refer to objects in SPEC macro source code files and are possibly hyperlinked if a matching identifier is found:

:spec:def:

Reference a SPEC macro definition by name. (Do not include the argument list.)

An example ``def`` macro: :spec:def:`demo_def`

An example def macro: demo_def

:spec:rdef:

Reference a SPEC run-time macro definition by name. (Do not include the argument list.)

An example ``rdef`` macro: :spec:rdef:`demo_rdef`

An example rdef macro: demo_rdef

:spec:cdef:

Reference a SPEC chained macro definition by name. (Do not include the argument list.)

An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef")`
An example ``cdef`` macro: :spec:cdef:`cdef("demo_cdef_more")`.

An example cdef macro: cdef("demo_cdef"). An example cdef macro: cdef("demo_cdef_more").

:spec:global:

Reference a global-scope variable.

An example ``global`` variable: :spec:global:`demo_global`

An example global variable: demo_global

:spec:local:

Reference a local-scope variable.

An example ``local`` variable: :spec:local:`demo_local`

An example local variable: demo_local

:spec:constant:

Reference a local-scope variable.

An example ``local`` variable: :spec:constant:`demo_constant`

An example local variable: demo_constant

Undeclared Variables

Undeclared variables (those with no formal global, local, constant, or array declaration) will not be documented. At least for now.

Footnotes

[1]hidden objects begin with one underline character, such as _hidden
[2]anonymous objects begin with at least two underline characters, such as __anon
[3]SPEC extended comments: http://www.certif.com/spec_help/chg5_01.html
[4]restructured text: http://docutils.sf.net/rst.html
[5]For now, the rendition is basic. This will be improved in a future revision.