mglib

Personal IDL library for M. Galloy

single page | use frames     calling     commenting     tags     customizing

Calling IDLdoc

To install IDLdoc, simply unzip and place the IDLdoc distribution in your IDL path. Do not separate the contents of the distribution; the code looks for files in locations relative to itself.

A typical call to IDLdoc is: IDL> idldoc, root='~/projects/mylib', output='~/projects/mylib-docs' This searches for .pro and .sav files in subdirectories of '~/projects/mylib' and places the output in '~/projects/mylib-docs'. The starting page for the output will be '~/projects/mylib-docs/index.html'.

Note: IDLdoc 3.0 copies source code into the output directory, so placing the output directory in your !PATH can cause IDL to choose a (possibly outdated) copy in the docs over the correct source file. It is recommended to either place your docs outside your !PATH or use the NOSOURCE keyword.

There are quite a few keywords to IDLdoc to set various specifications for the output. Further customization can be done through the templates (described in the "Producing customized output" section).

Keyword Description
ROOT root of directory hierarchy to document; this is the only required keyword
OUTPUT directory to place output; if not present, output will be placed in the ROOT directory
TITLE title of docs
SUBTITLE subtitle for docs
EMBED embed CSS stylesheet instead of linking to it (useful for documentation where individual pages must stand by themselves)
OVERVIEW filename of overview text and directory information
FOOTER filename of file to insert into the bottom of each page of docs
NONAVBAR set to not display the navbar
NOSOURCE set to not put source code into output
USER set to generate user-level docs (private parameters, files are not shown); the default is developer-level docs showing files and parameters
STATISTICS set to generate complexity statistics for routines
QUIET if set, don't print info messages, only print warnings and errors
SILENT if set, don't print any messages
FORMAT_STYLE style to use to parse file and routine comments ("idl", "idldoc", "verbatim", or "rst"); default is "idldoc"
MARKUP_STYLE markup used in comments ("rst" or "verbatim"); default is "verbatim"
COMMENT_STYLE output format for comments ("html", "rst", or "latex"); default is "html"
CHARSET set to the character set to be used for the output, default is utf-8
TEMPLATE_PREFIX prefix for template's names
TEMPLATE_LOCATION set to directory to find templates in
USE_LATEX set automatically typeset any LaTeX style equations in comments
ERROR set to a named variable to return the error state of the IDLdoc call; 0 indicates no error, anything else is an error
DEBUG set to allow crashes with a stack trace instead of the default simple message
HELP set to print out the syntax of an IDLdoc call
VERSION set to print out the version of IDLdoc
N_WARNINGS set to a named variable to return the number of warnings for the IDLdoc run
LOG_FILE if present, send messages to this filename instead of stdout
ASSISTANT obsolete; no longer used
PREFORMAT obsolete; no longer used
BROWSE_ROUTINES obsolete; no longer used

Commenting your code

Parsing of comments is handled by two different parsers: the format parser and the markup parser. The format parser breaks down the comment block into sections (i.e. finds the tags), handles attributes of tags that allow them, and then hands off the parsing of text comments to the markup parser (i.e. the description of a file, routine, parameter or other text in tags).

IDLdoc now accepts three different styles of commenting: IDLdoc style (the only style available in IDLdoc 2.0), the traditional IDL provided comment template, or a new restructured text style. The style to use can be specified with the FORMAT_STYLE keyword to IDLdoc (as a global setting for the run) or on each individual file with a "docformat" comment. Furthermore, a markup style which specifies how to parse comment blocks can also be set. The two markup styles are: verbatim (the only markup style in IDLdoc 2.0) or a restructured text style (they are described in the "Markup styles" section). The markup styles are specified via the MARKUP_STYLE keyword to IDLdoc or using a "docformat" comment.

For example, for the below file sets it format parser to be "idldoc" and its markup parser to be "verbatim": ; docformat = 'idldoc verbatim' ;+ ; Comments here are for the file. They are parsed using the verbatim ; markup style (i.e. they are just copied into the output). The tags ; below are parsed by the comment style parser, the idldoc format ; parser in this case, but the contents of the tags are then handed off ; to the markup parser. ; ; @author Michael Galloy (this text is also parsed by the markup parser) ;- ;+ ; These are some comments about my routine. Comments here are parsed by ; the markup parser. ; ; @returns status code (this is parsed by the markup parser) ;- function my_routine return, 1 end

Each format parser is discussed in its own section below.

It is recommended to use spaces instead of tabs to indent comments (though it is only required when using the rst parsers).

To be considered fully documented, a routine must have routine comments, document each parameter/keyword, and, if a function, document its return value.

IDLdoc format

Tags are prefixed with an "@" sign. Tag names are case-insensitive. For a list of all the tags, see the "Tags for IDL and rst formats" section. They must be the first non-whitespace character after the comment symbol ";" on a line. Arguments follow the tags after whitespace. Attributes are enclosed curly braces "{}".

For example, a tag with no arguments appears like: ; @abstract Tags with an argument: ; @returns string/strarr Tags with attributes appear like: ; @param x {in}{required}{type=fltarr} independent variable ; @param y {in}{required}{type=fltarr} dependent variable

IDL format

The standard IDL format is given below. The individual headers are described in the "Headers in IDL format" section. ;+ ; NAME: ; ROUTINE_NAME ; ; PURPOSE: ; Tell what your routine does here. I like to start with the words: ; "This function (or procedure) ..." ; Try to use the active, present tense. ; ; CATEGORY: ; Put a category (or categories) here. For example: ; Widgets. ; ; CALLING SEQUENCE: ; Write the calling sequence here. Include only positional parameters ; (i.e., NO KEYWORDS). For procedures, use the form: ; ; ROUTINE_NAME, Parameter1, Parameter2, Foobar ; ; Note that the routine name is ALL CAPS and arguments have Initial ; Caps. For functions, use the form: ; ; Result = FUNCTION_NAME(Parameter1, Parameter2, Foobar) ; ; Always use the "Result = " part to begin. This makes it super-obvious ; to the user that this routine is a function! ; ; INPUTS: ; Parm1: Describe the positional input parameters here. Note again ; that positional parameters are shown with Initial Caps. ; ; OPTIONAL INPUTS: ; Parm2: Describe optional inputs here. If you don't have any, just ; delete this section. ; ; KEYWORD PARAMETERS: ; KEY1: Document keyword parameters like this. Note that the keyword ; is shown in ALL CAPS! ; ; KEY2: Yet another keyword. Try to use the active, present tense ; when describing your keywords. For example, if this keyword ; is just a set or unset flag, say something like: ; "Set this keyword to use foobar subfloatation. The default ; is foobar superfloatation." ; ; OUTPUTS: ; Describe any outputs here. For example, "This function returns the ; foobar superflimpt version of the input array." This is where you ; should also document the return value for functions. ; ; OPTIONAL OUTPUTS: ; Describe optional outputs here. If the routine doesn't have any, ; just delete this section. ; ; COMMON BLOCKS: ; BLOCK1: Describe any common blocks here. If there are no COMMON ; blocks, just delete this entry. ; ; SIDE EFFECTS: ; Describe "side effects" here. There aren't any? Well, just delete ; this entry. ; ; RESTRICTIONS: ; Describe any "restrictions" here. Delete this section if there are ; no important restrictions. ; ; PROCEDURE: ; You can describe the foobar superfloatation method being used here. ; You might not need this section for your routine. ; ; EXAMPLE: ; Please provide a simple example here. An example from the ; DIALOG_PICKFILE documentation is shown below. Please try to ; include examples that do not rely on variables or data files ; that are not defined in the example code. Your example should ; execute properly if typed in at the IDL command line with no ; other preparation. ; ; Create a DIALOG_PICKFILE dialog that lets users select only ; files with the extension `pro'. Use the `Select File to Read' ; title and store the name of the selected file in the variable ; file. Enter: ; ; file = DIALOG_PICKFILE(/READ, FILTER = '*.pro') ; ; MODIFICATION HISTORY: ; Written by: Your name here, Date. ; July, 1994 Any additional mods get described here. Remember to ; change the stuff above if you add a new keyword or ; something! ;-

Restructured text format

Tags must be the first non-whitespace character on the line. Tag names are case-insensitive. For a list of all the tags, see the "Tags for IDL and rst formats" section. For tags with arguments, the arguments/attributes 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 commas, 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

Tags for IDLdoc and rst formats

Tags describe a particular aspect of the file or routine. There are slight differences in how the tags work between the IDLdoc and rst formats: some IDLdoc tags are singular and used repeatedly while their rst counterparts are plural but used only once. For example, in IDLdoc: ; @param x {in}{required}{type=fltarr} independent variable ; @param y {in}{required}{type=fltarr} dependent variable In rst this would be: ; :Params: ; x : in, required, type=fltarr ; independent variable ; y : in, required, type=fltarr ; dependent variable

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.
keyword keyword name see below Documents a keyword of the routine. IDLdoc format only.
keywords keyword name see below Documents keywords of the routine. rst format only.
obsolete none none If present, indicates the routine is obsolete.
param param name see below Documents a positional parameter of the routine. IDLdoc format only.
params param name see below Documents positional parameters of the routine. rst format only.
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.

Headers in IDL format

The following headers are available in an IDL style format.

Header name Description
NAME Name of the routine. Can be present, but is not used by IDLdoc.
PURPOSE Main description of the routine.
CATEGORY List of comma or period separated categories.
CALLING SEQUENCE Calling syntax for the routine. Can be present, but is not used by IDLdoc.
INPUTS List positional input parameters here. List as: Param1: describe param1 here Param2: describe param2 here
OPTIONAL INPUTS List optional input parameters here. Param3: describe param3 here
KEYWORD PARAMETERS Document the keyword parameters here. List them as: KEY1: key1 description KEY2: key2 description
OUTPUTS Document the return value.
OPTIONAL OUTPUTS Describe the optional outputs here.
COMMON BLOCKS List common blocks, as in: BLOCK1: description.
SIDE EFFECTS Describe side effects here.
RESTRICTIONS Describe restrictions.
PROCEDURE Describe/cite any algorithms being used in this routine.
EXAMPLE List a simple example.
MODIFICATION HISTORY List history of modifications to the routine: Written by: author name July 1994 Describe modifications done on this date

Markup styles

There are two markup styles that are used to format text (such as file/routine comments or the values of nearly any tag). The "verbatim" style simply copies exactly what is present. The "rst" style does three things:

  1. blank lines make paragraphs
  2. ending a line with two colons ("::"), skipping a line, and indenting the next section makes a code listing section
  3. the image directive will insert an image into the output and copy the image file to the output directory: .. image:: filename
There will be more features in the future, but for now these are quite handy.

Producing customized output

IDLdoc uses text file templates to create its output. These can be customized to produce any kind of text output: HTML, LaTeX, DocBook, restructured text, etc. The templates are located in the "templates" directory of the distribution. But instead of modifying them directly IDLdoc provides a mechanism to provide a location to your own sets of templates with the TEMPLATE_PREFIX and TEMPLATE_LOCATION keywords.

To produce output of a different style than HTML, use the COMMENT_STYLE keyword to specify a type of output (html, rst, and latex are provided). Other styles can be created as well.

Personal library of Michael Galloy
Contact me if you have enhancement requests or bug fixes.