Restructured text format style
Tags must be the first non-whitespace character on the line. Tag names are case-insensitive. A list of all the tags is shown in the next section. For tags with arguments, the attributes of the argument must be on the same line. Indentation is significant (spaces only—no tabs!); for tags with multiple arguments, each argument must be consistently indented at least two spaces. Attributes are separated from the argument by a ":" and from each other with commas. Comments for the argument must be further consistently indented at least two more spaces.
Tags with no arguments:
; :Abstract:
or with an argument
; :Returns: string/strarr
or arguments with attributes:
; :Params: ; x : in, required, type=fltarr ; independent variable ; y : in, required, type=fltarr ; dependent variable
For attributes with values that contain comments, either escape the comma with a "\" or enclose the value with double quotes. For example,
; :Params: ; fwd : out, optional, type=fltarr(2\, nSegments) ; streamline in the forward direction ; bwd : out, optional, type="fltarr(2, nSegments)" ; streamline in the backward direction
File tags
The following tags are available in file comments (i.e. comment headers not immediately preceeding/following a routine header).
| Tag name | Arguments | Attributes | Description |
|---|---|---|---|
| author | comments | none | Specifies the author of the file. |
| copyright | comments | none | Specifies the copyright information for the file. |
| examples | comments | none | Specifies examples of usage. |
| hidden | none | none | If present, indicates the file is not to be shown in the documentation. |
| history | comments | none | Lists the history for the file. |
| private | none | none | If present, indicates the file should not shown in user-level documentation (set with the USER keyword to IDLdoc). |
| property | property name, comments | none | Describes a property of a class (i.e. a keyword to getProperty, setProperty, or init). IDLdoc format only. |
| properties | property name, comments | none | Describes properties of a class (i.e. a keyword to getProperty, setProperty, or init). rst format only. |
| version | comments | none | Specifies the version of the file. |
Routine tags
The following tags are available for comments immediately before or after a routine header.
| Tag name | Arguments | Attributes | Description |
|---|---|---|---|
| abstract | none | none | If present, indicates the method is not implemented and present only to specify the interface to subclasses' implementations. |
| author | comments | none | Specifies the author of the routine. |
| bugs | comments | none | Specifies any issues found in the routine. |
| categories | list | none | Specifies a comma-separated list of category names. |
| copyright | comments | none | Specifies the copyright for the routine. |
| customer_id | comments | none | Specifies a customer ID for the routine. |
| description | comments | none | A tag for the standard comments for a routine. Will be appended to standard comments if both are present. Valid for rst format only. |
| examples | comments | none | Specifies examples of using the routine. |
| field | fieldname and comments | none | Specifies the name of the field followed by a description of the field. IDLdoc format only. |
| fields | fieldname and comments | none | Specifies the names of the field followed by a description of the field. rst format only. |
| file_comments | comments | none | Equivalent to the main section in file-level comments. |
| hidden | none | none | If present, indicate the routine should not be shown in the documentation. |
| hidden_file | none | none | If present, indicates the file containing this routine should not be shown in the documentation. |
| history | comments | none | Specifies the history of the routine. |
| inherits | none | none | Not used. |
| keywords | keyword name | see below | Documents keywords of the routine. |
| obsolete | none | none | If present, indicates the routine is obsolete. |
| params | param name | see below | Documents positional parameters of the routine. |
| post | comments | none | Specifies any post-conditions of the routine. |
| pre | comments | none | Specifies any pre-conditions of the routine. |
| private | none | none | If present, indicates the routine should not shown in user-level documentation (set with the USER keyword to IDLdoc). |
| private_file | comments | none | If present, indicates the file containing this routine should not shown in user-level documentation (set with the USER keyword to IDLdoc). |
| requires | comments | none | Specifies the IDL version of the routine. IDLdoc finds the routines requiring the highest IDL version and reports them on the warnings page. |
| returns | comments | none | Specifies the return value of the function. |
| todo | comments | none | Specifies any todo items left for the routine. |
| uses | comments | none | Specifies any other routines, classes, etc. needed by the routine. |
| version | comments | none | Specifies the version of the routine. |
Attributes
Attributes for tags that allow them (i.e. the "param" and "keyword" tags). The rst format separates attributes with a comma. If you need to use a comma in the value of the the attributes, either escape the comma with a "\" or use quotation marks for grouping the the value together. For example:
; :Params: ; fwd : out, optional, type=fltarr(2\, nSegments) ; streamline in the forward direction ; bwd : out, optional, type="fltarr(2, nSegments)" ; streamline in the backward direction
| Attribute name | Syntax | Description |
|---|---|---|
| in | in | Indicates the parameter is an input. |
| out | out | Indicates the parameter is an output. |
| optional | optional | Indicates argument is optional. |
| private | private | Indicates argument is not shown if IDLdoc is run in user mode (USER keyword to IDLdoc is set). |
| hidden | hidden | Indicates the argument is not to be shown. |
| required | required | Indicates argument is required. |
| type | type=comments | IDL data type of the argument. |
| default | default=comments | Default value of the argument. |
