Overview | Directory | Categories | Index | Search | File | Source | Help | Etc | Developer documentation |
This guide discusses how to mark up IDL pro code in order to insert more information into IDLdoc's output.
Comments on the routine and file level are placed between ";+" and ";-" lines before a routine in IDL source code. Content between these lines is copied verbatim into the IDLdoc output for the routine it appears before with the exception of the @-preceded "tags" listed in tables below. Once an @ appears in the comments, IDLdoc processes all remaining lines of the comments as tags. To place a non-tag defining "@" in your comments, escape it with a "\", as in "email_address\@rsinc.com".
In the following example, the @author tag is used to indicate an author of the code. The second "@" is escaped to allow its literal use in the email address:
; @author Michael Galloy, mgalloy\@rsinc.com
There are many tags which describe an individual routine. Each tag name appears after an "@" sign as the first non-whitespace character after the ;. The tags are described below.
Tag | Description |
---|---|
abstract | Presence of the this tag indicates this method is abstract. This is intended for use with methods of a class which are not intended to be called, but are only provided as documenting an interface that a subclass will override. |
author | Text following this tag appears in a list of attributes of the routine marked as "Author." |
bugs | Text that follows this tag is copied into a bug attribute of the routine and placed in a library wide listing which documents known failings of routines. |
categories |
Text following this tag is used as a comma separated list
of categories of the routine. The syntax is:
; @categories math, input/outputCategory names are case-sensitive and may contain any characters except commas (though whitespace at the beginning and end will be removed). |
copyright | Text following this tag appears in a list of attributes of the routine marked as "Copyright." |
customer_id | Text following this tag appears in a list of attributes of the routine marked as "Customer ID." |
examples | Text following this tag is copied into an examples attribute of the routine; it is intended to have example code of using the routine. |
field |
For routines in files that end in "__define", this
provides documentation of a member variable of a
class/structure. The syntax is
; @field field_name commentwhere "field" matches one of the structure field names of the structure type/class being defined. |
hidden | Presence of this tag hides this routine in IDLdoc output. |
history | Text following this tag is copied into a history attribute of the routine; it is intended to have a history of the creators and modifiers of the source code of the routine. |
inherits | Obsolete. Intended to provide the parent class of the documented class, but this is automatically handled by IDLdoc now (as long as class definitions are in files that end "__define"). |
keyword |
This tag documents a single keyword parameter to the
routine. This syntax is
; @keyword keyword_name attributes commentAttributes further describe keyword and detailed in the section below. The comment may be an text and is copied into the IDLdoc output. |
obsolete | Presence of this tag marks the routine as obsolete. |
param |
This tag documents a single keyword parameter to the
routine. This syntax is
; @param keyword_name attributes commentAttributes further describe keyword and detailed in the section below. The comment may be an text and is copied into the IDLdoc output. |
pre | Text following this tag will be copied to a pre attribute of the routine; it is intended to give conditions the routine assumes to be true before it runs. |
post | Text following this tag will be copied to a post attribute of the routine; it is intended to give conditions the routine assumes to be true after it runs. |
private | Presence of this tag will hide this routine in IDLdoc output if IDLdoc is run in "user" mode. |
requires |
Text following this tag is copied into the "Requires"
attribute of the routine; it is intended to provide
the version of IDL required to run the routine. For
example,
; @requires IDL 6.2will simply cause "IDL 6.2" to appear in the "Requires" attribute. |
restrictions | Text following this tag is copied into the "Restrictions" attribute of the routine; it is intended to provide any restrictions on the use of the routine. |
returns | Text following this tag is copied into the "Returns" attribute of the routine; it is intended to provide information about return value of a function. |
todo | This tag places an item in a library-wide list of todo items. The text following the tag is copied into this list along with the routine it appears in it. |
uses | Text following this tag is placed in a uses attribute of the routine; it is intended to list routines that this routine calls. |
version | Text following this tag is placed in a version attribute of the routine; it is intended to give a version name/number of the routine. |
For each positional parameters or keyword tag additional attributes may be added in curly braces. For example,
; @param x {in}{required}{type=lonarr} x-axis data
The attributes are described below.
Attribute | Description |
---|---|
default | This atrribute defines the default value of the parameter. Any string may be entered and is echoed in the IDLdoc output. |
hidden | This attribute hides this parameter in IDLdoc output. |
in | This attribute marks the parameter as an input to the routine. |
optional | This attribute marks the parameter as optional; the routine does not always need this parameter, although there might be cases where the parameter is required (depending on the presence and value of other parameters). |
out | This attribute marks the parameter as an output to the routine. This routine expects a named variable to be passed to this parameter (if passed at all). |
private | This attribute hides this parameter in IDLdoc output when IDLdoc is run in "user" mode and marking it as "private" when run in "developer" mode. |
required | This attribute marks the parameter as required. |
type | This atrribute defines the data type of the parameter. Any string may be entered and is echoed in the IDLdoc output. The special type "boolean" will cause the calling syntax in IDLdoc output to use the IDL online help syntax of prepending a "/" to the parameter name. |
Some tags may appear in the comments for any routine in a file because they document attributes of the file. These tags are described below.
Tag | Description |
---|---|
file_comments | Text following the tag is copied to the top of the file in the IDLdoc output i.e. it is a comment on the file and not the routine it appears in. If there are multiple file_comments tags in the file, the comments will be concatenated in the order they are present in the file. |
hidden_file | Presence of this tag indicates this entire file should be hidden in IDLdoc output. |
private_file | Presence of this tag indicates this entire file should be hidden in IDLdoc output if IDLdoc is run in "user" mode, but shown when run in "developer" mode (the default). |
;+ ; Define the instance variables of the array_list. ; ; @file_comments An array_list is an object representing a variable ; length list of scalar elements of any single type. ; Array_lists support adding elements at the end of ; the vector only, but any element may be removed from ; the array_list. An iterator is provided for ; efficient and easy looping throught the elements of ; the array_list. ; ; @field data pointer to an array ; @field cur_size the current size of the data in the array ; @field max_size the maximum size of the data in the current array ; @field type type code (as in SIZE function) for the elements in the ; array_list ; @field sample_struct pointer to a structure if the type is ; "structure" ; @field iterators IDL_Container for the iterators of this array_list ; ; @requires IDL 6.0 ; ; @author Michael D. Galloy ; @history Created September 26, 2003 ; @copyright RSI, 2003 ;- pro array_list__define compile_opt idl2 define = { array_list, $ data:ptr_new(), $ cur_size:0L, $ max_size:0L, $ type:0L, $ sample_struct:ptr_new(), $ iterators:obj_new() $ } endAnother example routine, this time a simple function with a positional parameter and keyword:
;+ ; Returns [b, a] for a linear function y = a * x + b that sends ; inRange[0] -> range[0] and inRange[1] -> range[1]. ; ; @returns dblarr(2) ; @param inRange {in}{required}{type=2 element numeric array} input ; range ; @keyword range {in}{optional}{type=dblarr(2)}{default=[0.D, 1.D]} ; output range ; @categories math, object graphics ;- function linear_function, inRange, range=outRange compile_opt idl2 i_outRange = n_elements(outRange) eq 0 $ ? [0.D, 1.D] $ : double(outRange) scale = [i_outRange[0] * inRange[1] - i_outRange[1] * inRange[0], $ i_outRange[1] - i_outRange[0]] / (inRange[1] - inRange[0]) return, scale endOne more example, this time a function method with an output keyword.
;+ ; Finds the value associated with the given key. ; ; @returns the value of the associated key or -1L if not found ; @param key {in}{type=key type} key to look up ; @keyword found {out}{optional}{type=boolean} true if value found for ; given key ;- function hash_table::get, key, found=found
The "dir-overview" file in each directory of the library is copied into the directory overview file. Much of the content of the overview file is obtained from the PRO code files in the directory, but this allows header content as an overview of the all the files in the directory to be inserted at the top of the directory overview file.
The library overview file is a single file which is inserted into the opening page of the IDLdoc output. This file is copied verbatim into the IDLdoc output except for the following tag which allows for comments on the contents of the directories found in the library.
Tag | Description |
---|---|
dir |
The text following this tag is the relative path
(web-style, always with a /) to a directory in the
library and a comment which is copied into a table in
the opening page of the IDLdoc output.
; @dir algorithms/math mathematical routines |
Below is the IDLdoc generated documentation for the IDLdoc main routine.
idldoc, root=string[, output=string][, overview=string][, footer=string][, log_file=string][, /user][, /quiet][, /silent][, /embed][, /nonavbar][, title=string][, subtitle=string][, /statistics][, n_warnings=variable][, /browse_routines][, /preformat][, /assistant]
idldoc, root='C:\mycode'