=== Introduction ===

The [http://idldoc.idldev.com/attachment/wiki/GettingStarted/idldoc30-getting-started.mov?format=raw 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 [wiki:RstFormat 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 [wiki:IDLdocFormat 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 [wiki:IDLFormat IDL format].

More information about keywords to IDLdoc and syntax of comments for each of the format styles can be found on the [http://docs.idldev.com/idllib/idldoc-help.html "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).