IDLdoc project documentation

"The IDL code documentation project documentation"

IDLdoc developer's guide

This guide discusses how to mark up IDL pro code in order to insert more information into IDLdoc's output.

Comments on the routine and file level are placed between ";+" and ";-" lines before a routine in IDL source code. Content between these lines is copied verbatim into the IDLdoc output for the routine it appears before with the exception of the @-preceded "tags" listed in tables below. Once an @ appears in the comments, IDLdoc processes all remaining lines of the comments as tags. To place a non-tag defining "@" in your comments, escape it with a "\", as in "email_address\@rsinc.com".

In the following example, the @author tag is used to indicate an author of the code. The second "@" is escaped to allow its literal use in the email address:

; @author Michael Galloy, mgalloy\@rsinc.com

Routine level comments

There are many tags which describe an individual routine. Each tag name appears after an "@" sign as the first non-whitespace character after the ;. The tags are described below.

; @categories math, input/output

; @field field_name comment

; @keyword keyword_name attributes comment

; @param keyword_name attributes comment

; @requires IDL 6.2

For each positional parameters or keyword tag additional attributes may be added in curly braces. For example,

; @param x {in}{required}{type=lonarr} x-axis data

The attributes are described below.

File level comments

Some tags may appear in the comments for any routine in a file because they document attributes of the file. These tags are described below.

Examples

;+
; Define the instance variables of the array_list.
;
; @file_comments An array_list is an object representing a variable
;                length list of scalar elements of any single type.
;                Array_lists support adding elements at the end of
;                the vector only, but any element may be removed from
;                the array_list. An iterator is provided for
;                efficient and easy looping throught the elements of
;                the array_list.
;
; @field data pointer to an array
; @field cur_size the current size of the data in the array
; @field max_size the maximum size of the data in the current array
; @field type type code (as in SIZE function) for the elements in the
;        array_list
; @field sample_struct pointer to a structure if the type is
;        "structure"
; @field iterators IDL_Container for the iterators of this array_list
;
; @requires IDL 6.0
;
; @author Michael D. Galloy
; @history Created September 26, 2003
; @copyright RSI, 2003
;-
pro array_list__define
    compile_opt idl2

    define = { array_list, $
        data:ptr_new(), $
        cur_size:0L, $
        max_size:0L, $
        type:0L, $
        sample_struct:ptr_new(), $
        iterators:obj_new() $
        }
end

;+
; Returns [b, a] for a linear function y = a * x + b that sends
; inRange[0] -> range[0] and inRange[1] -> range[1].
;
; @returns dblarr(2)
; @param inRange {in}{required}{type=2 element numeric array} input
;        range
; @keyword range {in}{optional}{type=dblarr(2)}{default=[0.D, 1.D]}
;          output range
; @categories math, object graphics
;-
function linear_function, inRange, range=outRange
    compile_opt idl2

    i_outRange = n_elements(outRange) eq 0 $
        ? [0.D, 1.D] $
        : double(outRange)

    scale = [i_outRange[0] * inRange[1] - i_outRange[1] * inRange[0], $
        i_outRange[1] - i_outRange[0]] / (inRange[1] - inRange[0])
    return, scale
end

;+
; Finds the value associated with the given key.
;
; @returns the value of the associated key or -1L if not found
; @param key {in}{type=key type} key to look up
; @keyword found {out}{optional}{type=boolean} true if value found for
;          given key
;-
function hash_table::get, key, found=found

Directory overviews

The "dir-overview" file in each directory of the library is copied into the directory overview file. Much of the content of the overview file is obtained from the PRO code files in the directory, but this allows header content as an overview of the all the files in the directory to be inserted at the top of the directory overview file.

Library overview

The library overview file is a single file which is inserted into the opening page of the IDLdoc output. This file is copied verbatim into the IDLdoc output except for the following tag which allows for comments on the contents of the directories found in the library.

; @dir algorithms/math mathematical routines

Syntax of IDLdoc routine

Below is the IDLdoc generated documentation for the IDLdoc main routine.