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 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 add to the documentation, use one of three format styles:

• IDL (the IDL header template)
• IDLdoc (the old @tag based style)
• rst (a new restructured text based style)

The format for a library can be set using the FORMAT_STYLE keyword to IDLDOC. 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).

Next, the IDLdoc style:

;+
; 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

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

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).