|Revision 738, 22.0 KB (checked in by mgalloy, 2 years ago)|
IDLdoc 3.3 Tutorial
This tutorial attempts to provide a friendly guide to start using IDLdoc. See the companion reference guide for a more detailed listing of all the options that IDLdoc provides.
IDLdoc generates nicely formatted API documentation directly from source code. If the documentation is close to the code it is much more likely to be kept up-to-date. As much as possible is generated directly from the source code itself.
IDLdoc goals are to:
- provide browsable API documentation for both developers and users of the code base
- indicate portions of the API that are not documented
- analyze code for aspects like complexity
There are similar tools for other languages, notably:
- Javadoc for Java
- Doxygen for multiple Languages
- Sphinx for Python
IDLdoc can easily do code introspection because it is written in IDL.
This tutorial intends to get a new user up to speed in using IDLdoc in the simplest way using the newer, more modern style of IDLdoc commenting. Don't worry, though, IDLdoc still supports legacy commenting styles so you don't have to go changing existing documentation (unless you want to make use of some of the cool, new features!). Experienced users will probably learn some new things too, since documentation for IDLdoc has been spotty in the past.
To install IDLdoc, simply unzip and place the IDLdoc .sav file, or the src/ directory if you are installing the IDLdoc source distribution, in your IDL path.
Do not separate the contents of the distribution; the code looks for files in locations relative to itself.
The basic calling sequence for IDLdoc specifies the path to a directory (or hierarchy of directories) with the ROOT keyword and, optionally, the path to where the output should be created:
IDL> idldoc, root='path/to/code', output='path/to/output'
If OUTPUT is not specified, output will be created inside the ROOT hierarchy next to the source files. By default, IDLdoc creates HTML documentation, though it can be customized to create other types of documentation. To view the documentation produced from the above command, open path/to/output/index.html in a web browser.
IDLdoc will generate useful documentation from any valid IDL code, showing the calling sequence of routines even if there are no comments, or no comments in a format that IDLdoc recognizes, in the source code. But for more useful documentation, comments formatted in a simple manner that IDLdoc recognizes can be parsed and placed into the output documentation.
IDLdoc examines files with .pro, .sav, .dlm, and .idldoc extensions. Source code and specially formatted comments in .pro files are parsed. Save files, of either the code or data varieties, are examined for their contents and listing of the routines or variables contained are produced. DLM files produce a similar, but more limited, output as normal source code files. Finally, .idldoc files are a way of including documentation that is common to several items, such as an overview of a directory or a page describing a topic that several routines refer to.
Two keywords you most likely will want to specify are TITLE and SUBTITLE. Set these to string values to be displayed prominently on your documentation. For example, the command used to generate the API documentation for the IDLdoc project itself is:
idldoc, root='src', output='api-docs', $ title='API documentation for IDLdoc ' + idldoc_version(), $ subtitle='IDLdoc ' + idldoc_version(/full), /statistics, $ index_level=1, overview='overview', footer='footer', /embed, $ format_style='rst', markup_style='rst'
This places the IDLdoc version information into the title/subtitle of the documentation. We'll talk about some of the other options in the following sections.
Note: By default, IDLdoc 3.0 copies source code into the output directory, so placing the output directory in your !PATH can cause IDL to choose the (possibly outdated) copy in the doc output directory over the correct source file. It is recommended to either place your docs outside your !PATH or use the NOSOURCE keyword.
The keywords used when IDLdoc is run provide some options in the type of output produced.
The USER keyword specifies whether "user" or "developer" documentation is produced. User documentation is appropriate for users of a library. Directories, files, routines, and keywords/parameters can be marked to not show up in user documentation by using the "Private" tag. For example, the MG_H5_DUMP routine has a few helper routines that are not intended for end users to call:
;+ ; Return a string representing an IDL declaration of the given item ; (attribute or dataset). ; ; :Private: ; ; :Returns: ; string ; ; :Params: ; typeId : in, required, type=long ; type identifier ; spaceId : in, required, type=long ; dataspace identifier ;- function mg_h5_dump_typedecl, typeId, spaceId
Individual keywords or parameters use a attribute to mark it as private. For instance, the MG_STREPLACE has a private keyword START that is not intended for users of the library routine, but is used by internal calls to the routine. The keyword's documentation is:
; start : out, optional, type=integral, default=0, private ; index into string of where to start looking for the pattern
Developer documentation is the default and will show items marked as private (though there is a "Hidden" tag for not showing an item in any documentation).
When producing HTML documentation, there are often two cases that need to be handled:
- documentation served on a web site and intended to be served as a full collection
- documentation pages intended to be handed out individually, e.g., giving someone a .pro file and its generated HTML documentation file
In the later case, it is often useful to set the EMBED and NONAVBAR keywords. The EMBED keyword embeds the, rather large, CSS file into each HTML page. This is inefficient for a full documentation set on a web site because in that situation, each page can just refer to a common .css file. The NONAVBAR keyword simply omits the navigation bar at the top of the page which is not needed when only one HTML page is given but useful to navigate a full documentation set.
The FOOTER keyword can specify a file to include at the bottom of each page of output. This file is included verbatim in the output, so it should be already be in the format of the output.
By default, IDLdoc will copy the source code and put a link to it in the output. Use the NOSOURCE keyword to indicate that source code should not be copied or linked to. If the source code should be linked to, but not copied use SOURCE_LINK to specify relative (SOURCE_LINK=1) or absolute (SOURCE_LINK=2) links.
If the STATISTICS keywords is set, IDLdoc will compute certain measures of the code's complexity like the number of lines in a routine and the cyclomatic complexity. Use the COMPLEXITY_CUTOFFS and ROUTINE_LINE_CUTOFFS to specify to 2-element arrays which specify the warning and flagged levels. The defaults are [10, 20] for COMPLEXITY_CUTOFFS and [75, 150] for ROUTINE_LINE_CUTOFFS.
The project site for IDLdoc, idldoc.idldev.com, contains more information about IDLdoc including the FAQ, the mailing list, ticket system, and downloads of all versions along with their release notes.