In-Line Documentation

Documentation for Miriad tasks and subroutines is included as comments within the body of the code (delimited by special ``directives''). This documentation is stripped out by the doc program to produce a .doc file. This .doc file is then used by the on-line help facilities and the manual generation utilities.

This documentation should be at the head of the source code. In FORTRAN notation, the documentation ``directives'' are:

c=  [routine name] [one-line description]   (for programs)
c*  [routine name] [one-line description]   (for subroutines)
c&  programmer ID
c:  comma-separated list of categories
c+
c   start of multi-line description block
c@  keyword                                 (for tasks)
c   multi-line keyword description          (for tasks)
c<  standard keyword                        (for tasks - deprecated form)
c--

For FORTRAN, comment lines can begin with either an uppercase or a lowercase c. In-line documentation in C is analogous, except that comment lines begin with a /*. Note also that once a /* is entered, everything until the next */ is considered a comment; it is the programmer's responsibility to determine where to place the */.

The entries in the comma-separated list of categories should be:

For executables:
General	Utility	Data Transfer	Visual Display
Calibration	uv Analysis	Map Making	Deconvolution
Plotting	Map Manipulation	Map Combination	Map Analysis
Profile Analysis	Model Fitting	Tools	Other
For subroutines:
Baselines	Calibration	Convolution	Coordinates
Display	Error-Handling	Files	Fits
Fourier-Transform	Gridding	Header-I/O	History
Image-Analysis	Image-I/O	Interpolation	Least-Squares
Log-File	Low-Level-I/O	Mathematics	Model
PGPLOT	Plotting	Polynomials	Region-of-Interest
SCILIB	Sorting	Strings	Terminal-I/O
Text-I/O	Transpose	TV	User-Input
User-Interaction	Utilities	uv-Data	uv-I/O
Zeeman	Other