Overview files are a simple way to give an introduction to a viewer of your IDLdoc’ed library. The main overview file is simple to specify when you run IDLdoc. For example, to specify the file “overview” in the current directory, use:

idldoc, root=my_root, overview='overview'

when you IDLdoc your library. There are also directory specific overview files, but first consider the contents of the main overview file.

What’s in the overview file and how is it used? Here is the current overview file for my library.

Library routines for the personal library of Michael Galloy.

@dir collection Objects implementing various types of collections.
@dir envi user functions for ENVI
@dir math miscellaneous mathematical routines
@dir objectgraphics helper routines and classes for using object graphics
@dir sorting searching and sorting routines
@dir sparklines routines involving sparklines (simple word-size graphics originated by Edward Tufte)
@dir utility utility routines
@dir web world wide web related routines
@dir widgets tools and components for making widget (GUI) programs

The overview file starts off with free-form comments that can include HTML. IDLdoc copies these comments directly to the overview page (the first page you see when you look at an IDLdoc’ed library). Then the first @ sign starts the tag section (this is just like the IDLdoc comments before a routine). The only tag currently accepted for overview files is the “dir” tag that specifies comments to include for the directory listed immediately after the dir tag. These directory comments are placed into a table of the directories in the library directly below the free-form comments above.

The directory overviews are constructed from the @file_comments tags of the individual files in the directory. It’s handy to put at least a one sentence description of the contents of the file into the header for one of the routines in the file (it doesn’t matter to IDLdoc which routine it is).

Next up for the IDLdoc series of articles is an explanation of the template system in IDLdoc 2.0. This is one part of IDLdoc that I would like to somehow release it as a separate package to download. It allows you to write some type of text output (like HTML, XML, LaTeX, DocBook, etc) that has place holders for data that are filled in when the template is parsed. In IDLdoc, all the output is “templatized” so that it can be changed without modifying any of IDLdoc’s code.

The previous article about IDLdoc showed how to get and run IDLdoc on your library without changing any of your code. Now, what if you are willing to add special tags to your comments for IDLdoc’s use?

So here is just the header of the MG_N_SMALLEST routine with a few of the most common tags in the comments:

;+
; Finds the n smallest elements of a data array. This algorithm works
; fastest on uniformly distributed data. The worst case for it is a
; single smallest data element and all other elements with another
; value. This will be nearly equivalent to just sorting all the
; elements and choosing the first n elements.
;
; @returns index array
;
; @param data {in}{required}{type=numeric array} data array of any
;             numeric type (except complex/dcomplex)
; @param n {in}{required}{type=integer} number of smallest elements
;          to find
; @keyword largest {in}{optional}{type=boolean} set to find n largest
;          elements
;-
function mg_n_smallest, data, n, largest=largest

These comments produce this output.

There are other tags to document authors, history of the code, copyright, assumptions, category the code addresses, etc. For a complete list of the tags allowed in IDLdoc 2.0, see the developer’s help page (produced by IDLdoc when it runs and also included in the distribution of IDLdoc in the “docs” directory).

Next, I’ll talk about customizing the overview pages and then on to some of the more advanced features.

IDLdoc is a tool to generate documentation for IDL code. The generated documentation has been traditionally been HTML web pages, but with IDLdoc 2.0 the documentation can easily be capatible with the IDL Assistant or (with a bit more work) any text file type such as LaTeX, XML, Docbook, etc. Examples of IDLdoc output are my published library and demos. Special comments understood by IDLdoc can document specific characteristics of your code, but IDLdoc can produce (at least somewhat) useful output of nearly any IDL code.

Steps to document your library with minimal work

You can customize the output of IDLdoc quite a bit, but if you just want the basics without much work, try:

1. Download IDLdoc 2.0.
2. Unzip IDLdoc into a directory in your path.
3. If your library is in libdir then use the command:

idldoc, root=libdir, output=docdir

The directory libdir is the path to the root directory of your library and docdir is the path to the documentation to be produced (the directory will be created if it doesn’t exist).

Even if you haven’t documented your code at all (much less with special IDLdoc tags), this will still produce a browseable, searchable set of web pages that document the routine names and parameters for your library.

If you have comments before your routines in the standard format (starting with a ;+ line and ending with a ;- line), IDLdoc will use them for the comments for the routine. Using the PREFORMAT to IDLDOC might produce better looking results if you have lined your comments up vertically in any way.

After producing your documentation, go todocdir and bring up index.html in your favorite browser to see the results. For more information, see the “Help” link in the navigation bar near the top of the page, the file idldoc-help.html in the docs directory of the IDLdoc distribution, or stayed tuned to this site for more articles. Next up: how to add special “tags” to your comments that give IDLdoc more specific information.