|
Developer Documentation |
|||||||||
prev file | next file | ||||||||||
SUMMARY: fields | routine DETAILS: routine | ||||||||||
Only comments in between ;+ and ;- markers (as the first non-whitespace items on their lines) before a routine are parsed by IDLdoc. Text (including HTML code) is simply copied verbatim to the IDLdoc HTML file until the first tag is encountered.
Tags are prefixed by an '@' sign which also serves as a delimiter between the content of the previous tag and its own content. The parameters to the tags are whitespace delimited. Often tags will have a parameter or two and then use the remainder of the tag content as a single parameter. Once an '@' sign appears in an IDLdoc comment, all remaining comment is interpreted as tags or contents of tags.
Also, certain tags accept further attributes. Attributes are enclosed in curly braces {}. For example, the param and keyword tags to comment positional parameters of a routine, accepts the attributes "in", "out", "type=", "optional", "required", and "default=".
The below tags are processed by IDLdoc in headings for routines. Note to use an @ sign in a routine's comments, it must be escaped with a \ immediately before the @.
Routine Tags | |
abstract | Indicates the method is abstract (ie. the routine is not implemented) |
author | Author of the routine |
bugs | Comment to describing the known bugs for the routine |
copyright | Copyright information |
examples | Example code |
field | Comments for fields of a class defined in a file that ends in __DEFINE.PRO |
file_comments | Comments for the entire file. |
hidden | Hides this routine from IDLdoc |
hidden_file | Hides the file this routine is part of from IDLdoc |
history | History of modifcations of the routine |
inherits | parent class of the class (if class definition) |
keyword | Keyword parameter; attributes of this tag are {in}, {out}, {optional}, {type=name}, {default=value}, {private}, {required} |
obsolete | Indicates the routines is obsolete |
param | Positional parameter; attributes of this tag are {in}, {out}, {optional}, {type=name}, {default=value}, {private}, {required} |
pre | Indicates a pre-condition (requirement) for the routine to run |
post | Indicates a post-condition that should be true when the routine has finished |
private | Indicates the routine is not intended to be called by users. Routines with this tag set will be hidden if the USER keyword to IDLdoc is set. |
private_file | Indicates the file this routine is part of is not intended to be called by users of the file. Routines with this tag set will be hidden if the USER keyword to IDLdoc is set. |
returns | Return information for a function |
requires | Version of IDL required to run routine |
restrictions | Restrictions on the use of the routine |
uses | Which non-RSI IDL routines this routine needs |
version | Current version of the routine |
Below is the comment header for the IDLdoc routine itself and appears immediately before the IDLdoc routine definition:
;+ ; Calling routine for IDLdoc. ; ; @file_comments IDLdoc is a hypertext documentation system for IDL code. It ; is intended to show the API of a library of code in an easy to browse ; manner. It produces HTML pages -- one page per '.pro' file, as ; well as directory listing, overview pages, and an index of files, routines, ; keywords, and parameter names. ; ; p Unmarked code may be processed by IDLdoc to produce a browseable ; listing of routines and their arguments. But to obtain more useful ; results, the source can be marked to produce formatted comments in ; the output. Each routine has special tags to indicate particular ; information for IDLdoc formatting use. HTML markup tags may be used ; anywhere comments are expected. See the ; A HREF="idldoc_files.html"help/A for individual files for specifics about ; the tags available. ; ; p For a more an example of code that has been documented using IDLdoc, ; check IDLdoc's source for its comments and compare to its output. ; ; p Class listings and fields summary will be generated for files which ; end with __DEFINE.PRO. Use the "field" tag to make comments on each ; field of the class/structure defined. ; ; p An overview file can be specified with the OVERVIEW keyword to IDLdoc. ; This file is a plain text file with comments (which can contain HTML codes) ; that will be displayed on a summary page. The below tags are processed by ; IDLdoc. ; ; p ; ; table width="100%" border="1" cellspacing="0" cellpadding="3" ; tr bgcolor="#DDDDDD"td colspan="2"bOverview Tags/b/td/tr ; trtd width="100" align="right" valign="top"dir/td ; tdComment for a directory. The first parameter to dir is the directory ; name relative to the root dir. The rest of the tag content is the comment. ; /td/tr ; /table ; ; p The style of the output of IDLdoc can be changed by editing the ; cascading style sheet used: idldoc.css found in the same directory ; as IDLdoc. ; ; p This help was produced by IDLdoc. ; ; @examples To run IDLdoc, try: ; centercodeidldoc, root='C:\\mycode'/code/center ; where C:\\mycode is the root of a directory tree containing IDL ; .pro files. ; ; @keyword root {in}{required}{type=string} root directory for IDLdoc's ; recursive search for .pro files. IDLdoc will find any ; files with the '.pro' suffix and include them in its file ; listings. Only directories with '.pro' files in them are ; included in the directory listings. ; @keyword browse_routines {in}{optional}{type=boolean} set to include a frame ; to browse through the routines of the current file ; @keyword nonavbar {in}{optional}{type=boolean} set to exclude the ; navigation bar at the top of each page ; @keyword output {in}{optional}{type=string}{default=same as root} ; directory in which to create the HTML output and possible ; subdirectories ; @keyword overview {in}{optional}{type=string} filepath to a file containing ; the summary of the package information about each directory in the ; package. ; @keyword quiet {in}{optional}{type=boolean} if set, print only ; warnings ; @keyword silent {in}{optional}{type=boolean} if set, print no ; messages ; @keyword user {in}{optional}{type=boolean} set to create a ; listing appropriate for emusers/em of the given ; library hierarchy; the default is to create documentation ; suited to developers. If set private routines are not ; shown in the documentation. ; @keyword embed {in}{optional}{type=boolean} if set, embeds style ; sheet in each HTML document; if this is not set, each HTML ; file will be looking for the cascading style sheet idldoc.css ; in the directory specified for the ROOT keyword ; @keyword footer {in}{optional}{type=string} filename for a footer ; to be placed at the bottom of files; this file can contain any valid ; HTML ; @keyword n_warnings {out}{optional}{type=integer} set to a named variable to ; contain the total number of warnings issued during the run ; @keyword title {in}{optional}{type=string}{default=Research Systems} title to ; place in the upper right of all generated pages ; @keyword statistics {in}{optional}{type=boolean} set to include statistics ; about each file ; @keyword subtitle {in}{optional}{type=string}{default=IDL version} subtitle to ; place in the upper right of all generated pages ; @requires IDL 6.0 ; @author Michael D. Galloy ; @copyright RSI, 2002 ;-