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
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.
Contact me if you have enhancement requests or bug fixes.