Introduction

The Getting Started with IDLdoc 3.0 video gives a two minute demo of using IDLdoc.

Getting Started

IDLdoc can produce documentation for any valid IDL code (routine, main-level programs, batch files or save files). Optionally, if the code contains specially marked up comments, those will be included in the output in the appropriate places. To get started, try:

IDL> idldoc, root=myRootDir, output=outputDir

where myRootDir is the location of some IDL code and outputDir is the location where the HTML output should be created. To look at the output, load outputDir\index.html in your web browser. No matter what kind of comments are present (if any), IDLdoc will produce a browsable listing of the directories, files, routines, and parameters in the library.

To add comments that IDLdoc can understand and place in the output documentation, use one of three format styles:

• IDL (the standard IDL header template)
• IDLdoc (the old @tag based style, similar to Javadoc's style)
• rst (a new restructured text based style, understood by the IDL Workbench)

The format for a library can be set by specifying the FORMAT_STYLE keyword to IDLDOC to 'IDL', 'IDLdoc' or 'rst'. Individual files in a library can be documented in differing styles by adding:

; docformat = 'rst'

at the top of each file (replacing rst with one of the above style names).

Next, let's document an example routine in the format of each style. First, an example using the rst style is below:

;+
; Compute the H5D_SELECT_HYPERSLAB arguments from the bounds.
;
; :Params:
;    bounds : in, required, type="lonarr(ndims, 3)"
;       bounds 
;
; :Keywords:
;    start : out, optional, type=lonarr(ndims)
;       input for start argument to H5S_SELECT_HYPERSLAB
;    count : out, optional, type=lonarr(ndims)
;       input for count argument to H5S_SELECT_HYPERSLAB
;    block : out, optional, type=lonarr(ndims)
;       input for block keyword to H5S_SELECT_HYPERSLAB
;    stride : out, optional, type=lonarr(ndims)
;       input for stride keyword to H5S_SELECT_HYPERSLAB
;-
pro mg_h5_getdata_computeslab, bounds, $
                               start=start, count=count, $
                               block=block, stride=stride

The indentation is significant in the rst style, so make sure to consistently indent at least two spaces (no tabs). For more details, see rst format.

Next, the IDLdoc style documentation for the same routine:

;+
; Compute the H5D_SELECT_HYPERSLAB arguments from the bounds.
;
; @param bounds {in}{required}{type=lonarr(ndims, 3)} bounds 
;
; @keyword start {out}{optional}{type=lonarr(ndims)}
;       input for start argument to H5S_SELECT_HYPERSLAB
; @keyword count {out}{optional}{type=lonarr(ndims)}
;       input for count argument to H5S_SELECT_HYPERSLAB
; @keyword block {out}{optional}{type=lonarr(ndims)}
;       input for block keyword to H5S_SELECT_HYPERSLAB
; @keyword stride {out}{optional}{type=lonarr(ndims)}
;       input for stride keyword to H5S_SELECT_HYPERSLAB
;-
pro mg_h5_getdata_computeslab, bounds, $
                               start=start, count=count, $
                               block=block, stride=stride

For more details, see IDLdoc format?. Finally, the IDL template style:

;+
; Compute the H5D_SELECT_HYPERSLAB arguments from the bounds.
;
; INPUTS:
;    bounds: bounds 
;
; KEYWORD PARAMETERS:
;    start: input for start argument to H5S_SELECT_HYPERSLAB
;    count: input for count argument to H5S_SELECT_HYPERSLAB
;    block: input for block keyword to H5S_SELECT_HYPERSLAB
;    stride: input for stride keyword to H5S_SELECT_HYPERSLAB
;-
pro mg_h5_getdata_computeslab, bounds, $
                               start=start, count=count, $
                               block=block, stride=stride

For more details, see IDL format?.

More information about keywords to IDLdoc and syntax of comments for each of the format styles can be found on the  "Help" page in the output (the link is on the right of the main navigation bar at the top of any page in the output).