# Complete SSC R2.4.17 Web Services API

## Generated by IDLdoc

single page | use frames calling commenting tags customizing

## Calling IDLdoc

To install IDLdoc, simply unzip and place the IDLdoc distribution in your IDL path. Do not separate the contents of the distribution; the code looks for files in locations relative to itself.

A typical call to IDLdoc is: `IDL> idldoc, root='~/projects/mylib', output='~/projects/mylib-docs'` This searches for .pro and .sav files in subdirectories of '~/projects/mylib' and places the output in '~/projects/mylib-docs'. The starting page for the output will be '~/projects/mylib-docs/index.html'.

Note: IDLdoc 3.0 copies source code into the output directory, so placing the output directory in your !PATH can cause IDL to choose a (possibly outdated) copy in the docs over the correct source file. It is recommended to either place your docs outside your !PATH or use the NOSOURCE keyword.

There are quite a few keywords to IDLdoc to set various specifications for the output. Further customization can be done through the templates (described in the "Producing customized output" section).

Keyword | Description
ROOT | root of directory hierarchy to document; this is the only required keyword
OUTPUT | directory to place output; if not present, output will be placed in the ROOT directory
TITLE | title of docs
SUBTITLE | subtitle for docs
EMBED | embed CSS stylesheet instead of linking to it (useful for documentation where individual pages must stand by themselves)
OVERVIEW | filename of overview text and directory information
FOOTER | filename of file to insert into the bottom of each page of docs
NONAVBAR | set to not display the navbar
NOSOURCE | set to not put source code into output
USER | set to generate user-level docs (private parameters, files are not shown); the default is developer-level docs showing files and parameters
STATISTICS | set to generate complexity statistics for routines
QUIET | if set, don't print info messages, only print warnings and errors
SILENT | if set, don't print any messages
FORMAT_STYLE | style to use to parse file and routine comments ("idl", "idldoc", "verbatim", or "rst"); default is "idldoc"
MARKUP_STYLE | markup used in comments ("rst" or "verbatim"); default is "verbatim"
COMMENT_STYLE | output format for comments ("html", "rst", or "latex"); default is "html"
CHARSET | set to the character set to be used for the output, default is utf-8
TEMPLATE_PREFIX | prefix for template's names
TEMPLATE_LOCATION | set to directory to find templates in
USE_LATEX | set automatically typeset any LaTeX style equations in comments
ERROR | set to a named variable to return the error state of the IDLdoc call; 0 indicates no error, anything else is an error
DEBUG | set to allow crashes with a stack trace instead of the default simple message
HELP | set to print out the syntax of an IDLdoc call
VERSION | set to print out the version of IDLdoc
N_WARNINGS | set to a named variable to return the number of warnings for the IDLdoc run
LOG_FILE | if present, send messages to this filename instead of stdout
ASSISTANT | obsolete; no longer used
PREFORMAT | obsolete; no longer used
BROWSE_ROUTINES | obsolete; no longer used

## Commenting your code

Parsing of comments is handled by two different parsers: the format parser and the markup parser. The format parser breaks down the comment block into sections (i.e. finds the tags), handles attributes of tags that allow them, and then hands off the parsing of text comments to the markup parser (i.e. the description of a file, routine, parameter or other text in tags).

IDLdoc now accepts three different styles of commenting: IDLdoc style (the only style available in IDLdoc 2.0), the traditional IDL provided comment template, or a new restructured text style. The style to use can be specified with the FORMAT_STYLE keyword to IDLdoc (as a global setting for the run) or on each individual file with a "docformat" comment. Furthermore, a markup style which specifies how to parse comment blocks can also be set. The two markup styles are: verbatim (the only markup style in IDLdoc 2.0) or a restructured text style (they are described in the "Markup styles" section). The markup styles are specified via the MARKUP_STYLE keyword to IDLdoc or using a "docformat" comment.

For example, for the below file sets it format parser to be "idldoc" and its markup parser to be "verbatim": `; docformat = 'idldoc verbatim' ;+ ; Comments here are for the file. They are parsed using the verbatim ; markup style (i.e. they are just copied into the output). The tags ; below are parsed by the comment style parser, the idldoc format ; parser in this case, but the contents of the tags are then handed off ; to the markup parser. ; ; @author Michael Galloy (this text is also parsed by the markup parser) ;- ;+ ; These are some comments about my routine. Comments here are parsed by ; the markup parser. ; ; @returns status code (this is parsed by the markup parser) ;- function my_routine return, 1 end`

Each format parser is discussed in its own section below.

It is recommended to use spaces instead of tabs to indent comments (though it is only required when using the rst parsers).

To be considered fully documented, a routine must have routine comments, document each parameter/keyword, and, if a function, document its return value.

### IDLdoc format

Tags are prefixed with an "@" sign. Tag names are case-insensitive. For a list of all the tags, see the "Tags for IDL and rst formats" section. They must be the first non-whitespace character after the comment symbol ";" on a line. Arguments follow the tags after whitespace. Attributes are enclosed curly braces "{}".

For example, a tag with no arguments appears like: `; @abstract` Tags with an argument: `; @returns string/strarr` Tags with attributes appear like: `; @param x {in}{required}{type=fltarr} independent variable ; @param y {in}{required}{type=fltarr} dependent variable`

### IDL format

The standard IDL format is given below. The individual headers are described in the "Headers in IDL format" section. `;+ ; NAME: ; ROUTINE_NAME ; ; PURPOSE: ; Tell what your routine does here. I like to start with the words: ; "This function (or procedure) ..." ; Try to use the active, present tense. ; ; CATEGORY: ; Put a category (or categories) here. For example: ; Widgets. ; ; CALLING SEQUENCE: ; Write the calling sequence here. Include only positional parameters ; (i.e., NO KEYWORDS). For procedures, use the form: ; ; ROUTINE_NAME, Parameter1, Parameter2, Foobar ; ; Note that the routine name is ALL CAPS and arguments have Initial ; Caps. For functions, use the form: ; ; Result = FUNCTION_NAME(Parameter1, Parameter2, Foobar) ; ; Always use the "Result = " part to begin. This makes it super-obvious ; to the user that this routine is a function! ; ; INPUTS: ; Parm1: Describe the positional input parameters here. Note again ; that positional parameters are shown with Initial Caps. ; ; OPTIONAL INPUTS: ; Parm2: Describe optional inputs here. If you don't have any, just ; delete this section. ; ; KEYWORD PARAMETERS: ; KEY1: Document keyword parameters like this. Note that the keyword ; is shown in ALL CAPS! ; ; KEY2: Yet another keyword. Try to use the active, present tense ; when describing your keywords. For example, if this keyword ; is just a set or unset flag, say something like: ; "Set this keyword to use foobar subfloatation. The default ; is foobar superfloatation." ; ; OUTPUTS: ; Describe any outputs here. For example, "This function returns the ; foobar superflimpt version of the input array." This is where you ; should also document the return value for functions. ; ; OPTIONAL OUTPUTS: ; Describe optional outputs here. If the routine doesn't have any, ; just delete this section. ; ; COMMON BLOCKS: ; BLOCK1: Describe any common blocks here. If there are no COMMON ; blocks, just delete this entry. ; ; SIDE EFFECTS: ; Describe "side effects" here. There aren't any? Well, just delete ; this entry. ; ; RESTRICTIONS: ; Describe any "restrictions" here. Delete this section if there are ; no important restrictions. ; ; PROCEDURE: ; You can describe the foobar superfloatation method being used here. ; You might not need this section for your routine. ; ; EXAMPLE: ; Please provide a simple example here. An example from the ; DIALOG_PICKFILE documentation is shown below. Please try to ; include examples that do not rely on variables or data files ; that are not defined in the example code. Your example should ; execute properly if typed in at the IDL command line with no ; other preparation. ; ; Create a DIALOG_PICKFILE dialog that lets users select only ; files with the extension `pro'. Use the `Select File to Read' ; title and store the name of the selected file in the variable ; file. Enter: ; ; file = DIALOG_PICKFILE(/READ, FILTER = '*.pro') ; ; MODIFICATION HISTORY: ; Written by: Your name here, Date. ; July, 1994 Any additional mods get described here. Remember to ; change the stuff above if you add a new keyword or ; something! ;-`

### Restructured text format

Tags must be the first non-whitespace character on the line. Tag names are case-insensitive. For a list of all the tags, see the "Tags for IDL and rst formats" section. For tags with arguments, the arguments/attributes must be on the same line. Indentation is significant (spaces only—no tabs!); for tags with multiple arguments, each argument must be consistently indented at least two spaces. Attributes are separated from the argument by a ":" and from each other with commas. Comments for the argument must be further consistently indented at least two more spaces.

Tags with no arguments: `; :Abstract:` or with an argument `; :Returns: string/strarr` or arguments with attributes: `; :Params: ; x : in, required, type=fltarr ; independent variable ; y : in, required, type=fltarr ; dependent variable`

For attributes with values that contain commas, either escape the comma with a "\" or enclose the value with double quotes. For example, `; :Params: ; fwd : out, optional, type=fltarr(2\, nSegments) ; streamline in the forward direction ; bwd : out, optional, type="fltarr(2, nSegments)" ; streamline in the backward direction`

## Tags for IDLdoc and rst formats

Tags describe a particular aspect of the file or routine. There are slight differences in how the tags work between the IDLdoc and rst formats: some IDLdoc tags are singular and used repeatedly while their rst counterparts are plural but used only once. For example, in IDLdoc: `; @param x {in}{required}{type=fltarr} independent variable ; @param y {in}{required}{type=fltarr} dependent variable` In rst this would be: `; :Params: ; x : in, required, type=fltarr ; independent variable ; y : in, required, type=fltarr ; dependent variable`

### File tags

The following tags are available in file comments (i.e. comment headers not immediately preceeding/following a routine header).

Tag name | Arguments | Attributes | Description
author | comments | none | Specifies the author of the file.
copyright | comments | none | Specifies the copyright information for the file.
examples | comments | none | Specifies examples of usage.
hidden | none | none | If present, indicates the file is not to be shown in the documentation.
history | comments | none | Lists the history for the file.
private | none | none | If present, indicates the file should not shown in user-level documentation (set with the USER keyword to IDLdoc).
property | property name, comments | none | Describes a property of a class (i.e. a keyword to getProperty, setProperty, or init). IDLdoc format only.
properties | property name, comments | none | Describes properties of a class (i.e. a keyword to getProperty, setProperty, or init). rst format only.
version | comments | none | Specifies the version of the file.

### Routine tags

The following tags are available for comments immediately before or after a routine header.

Tag name | Arguments | Attributes | Description
abstract | none | none | If present, indicates the method is not implemented and present only to specify the interface to subclasses' implementations.
author | comments | none | Specifies the author of the routine.
bugs | comments | none | Specifies any issues found in the routine.
categories | list | none | Specifies a comma-separated list of category names.
copyright | comments | none | Specifies the copyright for the routine.
customer_id | comments | none | Specifies a customer ID for the routine.
description | comments | none | A tag for the standard comments for a routine. Will be appended to standard comments if both are present. Valid for rst format only.
examples | comments | none | Specifies examples of using the routine.
field | fieldname and comments | none | Specifies the name of the field followed by a description of the field. IDLdoc format only.
fields | fieldname and comments | none | Specifies the names of the field followed by a description of the field. rst format only.
file_comments | comments | none | Equivalent to the main section in file-level comments.
hidden | none | none | If present, indicate the routine should not be shown in the documentation.
hidden_file | none | none | If present, indicates the file containing this routine should not be shown in the documentation.
history | comments | none | Specifies the history of the routine.
inherits | none | none | Not used.
keyword | keyword name | see below | Documents a keyword of the routine. IDLdoc format only.
keywords | keyword name | see below | Documents keywords of the routine. rst format only.
obsolete | none | none | If present, indicates the routine is obsolete.
param | param name | see below | Documents a positional parameter of the routine. IDLdoc format only.
params | param name | see below | Documents positional parameters of the routine. rst format only.
post | comments | none | Specifies any post-conditions of the routine.
pre | comments | none | Specifies any pre-conditions of the routine.
private | none | none | If present, indicates the routine should not shown in user-level documentation (set with the USER keyword to IDLdoc).
private_file | comments | none | If present, indicates the file containing this routine should not shown in user-level documentation (set with the USER keyword to IDLdoc).
requires | comments | none | Specifies the IDL version of the routine. IDLdoc finds the routines requiring the highest IDL version and reports them on the warnings page.
returns | comments | none | Specifies the return value of the function.
todo | comments | none | Specifies any todo items left for the routine.
uses | comments | none | Specifies any other routines, classes, etc. needed by the routine.
version | comments | none | Specifies the version of the routine.

### Attributes

Attributes for tags that allow them (i.e. the "param" and "keyword" tags). The rst format separates attributes with a comma. If you need to use a comma in the value of the the attributes, either escape the comma with a "\" or use quotation marks for grouping the the value together. For example: `; :Params: ; fwd : out, optional, type=fltarr(2\, nSegments) ; streamline in the forward direction ; bwd : out, optional, type="fltarr(2, nSegments)" ; streamline in the backward direction`

Attribute name | Syntax | Description
in | `in` | Indicates the parameter is an input.
out | `out` | Indicates the parameter is an output.
optional | `optional` | Indicates argument is optional.
private | `private` | Indicates argument is not shown if IDLdoc is run in user mode (USER keyword to IDLdoc is set).
hidden | `hidden` | Indicates the argument is not to be shown.
required | `required` | Indicates argument is required.
type | `type=comments` | IDL data type of the argument.
default | `default=comments` | Default value of the argument.

## Headers in IDL format

The following headers are available in an IDL style format.

Header name | Description
NAME | Name of the routine. Can be present, but is not used by IDLdoc.
PURPOSE | Main description of the routine.
CATEGORY | List of comma or period separated categories.
CALLING SEQUENCE | Calling syntax for the routine. Can be present, but is not used by IDLdoc.
INPUTS | List positional input parameters here. List as: `Param1: describe param1 here Param2: describe param2 here`
OPTIONAL INPUTS | List optional input parameters here. `Param3: describe param3 here`
KEYWORD PARAMETERS | Document the keyword parameters here. List them as: `KEY1: key1 description KEY2: key2 description`
OUTPUTS | Document the return value.
OPTIONAL OUTPUTS | Describe the optional outputs here.
COMMON BLOCKS | List common blocks, as in: `BLOCK1: description.`
SIDE EFFECTS | Describe side effects here.
RESTRICTIONS | Describe restrictions.
PROCEDURE | Describe/cite any algorithms being used in this routine.
EXAMPLE | List a simple example.
MODIFICATION HISTORY | List history of modifications to the routine: `Written by: author name July 1994 Describe modifications done on this date`

## Markup styles

There are two markup styles that are used to format text (such as file/routine comments or the values of nearly any tag). The "verbatim" style simply copies exactly what is present. The "rst" style does three things:

1. blank lines make paragraphs
2. ending a line with two colons ("::"), skipping a line, and indenting the next section makes a code listing section
3. the image directive will insert an image into the output and copy the image file to the output directory: `.. image:: filename`

There will be more features in the future, but for now these are quite handy.

## Producing customized output

IDLdoc uses text file templates to create its output. These can be customized to produce any kind of text output: HTML, LaTeX, DocBook, restructured text, etc. The templates are located in the "templates" directory of the distribution. But instead of modifying them directly IDLdoc provides a mechanism to provide a location to your own sets of templates with the TEMPLATE_PREFIX and TEMPLATE_LOCATION keywords.

To produce output of a different style than HTML, use the COMMENT_STYLE keyword to specify a type of output (html, rst, and latex are provided). Other styles can be created as well.

SSC Feedback.