7. Documentation Standards

Documentation standards consist of two parts: in-line and external. In-line documentation aids in module debugging and maintenance. External documentation of support routines is typically used to assist in determining which subroutines to call and how to do so; whereas, external documentation of application modules is used to assist the user in operating the software in the correct manner.

7.1 In-Line Program Documentation

In-line documentation includes two particular areas: (1) The prologue is text describing the program unit that is placed at the beginning of the file before any code. This implies that there is only one prologue per file. Local subroutines do not need a full prologue since they will not be called by any routines except for those in the same file, but subroutines do need an algorithm description. The routines should be simple enough so that a few comments can explain how and what they do. (2) All code should contain text which identifies and describes each major block and any complicated code sequence.

Following is a list of the various aspects to be covered in the prologue and an explanation of the information that the programmer should include for each of these aspects. Not all of these sections are needed for every routine and therefore are marked optional. For example, since C supports good in-line documentation for variables, the variable sections are redundant and can be misleading if not maintained. These optional sections can be left out of a program prologue if they do not apply. For example, if a program has no algorithm references, the "ALGORITHM REFERENCES" section need not appear in the prologue.

             --Program Prologue-- 



NAME:

Name of the program.  


PURPOSE:

Brief description of what the program does.


EXTERNAL ASSOCIATIONS: (optional)

Describe how this module fits with other program units, including
which units must be run or called before or after it and also which
ones call it, if known.


FILE REFERENCES: (optional)

Describe all files, if any, referenced by this unit.


EXTERNAL VARIABLE REFERENCES:
 (optional)

List and describe all external variables referenced.  Describe
the function of each variable, including any limits on values. 
Include the variable's data type in the description.  If the 
variable is an array, give its dimension.  An external variable
is any variable which is accessed both within the current program 
unit and by some other program unit.  Examples of external 
variables are C external variables, FORTRAN common areas with a list
of associated variables, DCL global variables, TCL global 
variables, and shell global variables.


INTERNAL VARIABLES: (optional)

List and describe all internal variables in the same way as 
external variables.  Internal variables are variables which are 
not external.  Thus, all variables should appear as either externals
or internals.


PROGRAM HISTORY:

Include the date, the programmer, and a brief description and 
explanation of the changes.  Although the description should 
be kept short, it should include a list of all problems, limitations,
or new requirements which led to the change and how that change was 
implemented.  It should also include a problem report number.
 

COMPUTER HARDWARE AND/OR SOFTWARE LIMITATIONS:

List all limitations of the program unit relating to required 
hardware such as the type of host, peripheral devices, the type of 
operating system, OS feature, or related software.


PROJECT:

List the project which uses or requires this program unit.


ALGORITHM DESCRIPTION:

Describe in detail the algorithm which the entire program unit 
implements. This should be written in structured English, indented to 
show program structures.


A complicated program with many subroutines should include a treelike 
structure which shows the relationship of all the subroutines.


ALGORITHM REFERENCES:  (optional)

List sources used as references in writing the major algorithm(s) of the
program unit.

7.2 External Support Module Documentation

External support module documentation is documentation of a support module that is kept external to the program. This documentation would be useful to a programmer trying to understand the function of a piece of code or an entire package. It would also be useful to a programmer trying to use an entry point out of a library. It would not be useful to a typical user trying to run a program or package. The most important function of external program documentation is to provide programmers with instructions on how to use system or package-wide libraries. This type of information is absolutely necessary if programmers are to make efficient use of the libraries that LAS has available. 

                --Functional Guide Page--



FUNCTION NAME:

Short (one line hopefully) description of the entry point.


SYNTAX:

List the calling sequence for the entry point in its native language, 
identifying all parameters.


PARAMETERS:

For each parameter, list its type and significance.  For entry points 
which return a value, fully describe the use and significance of the 
returned value.  After fully describing the parameters, fully describe 
the entry; this includes describing in detail what it does.


DESCRIPTION:

Provide a detailed description of what the subroutine does and 
describe any interesting side effects of the routine.


RETURN VALUE:

List the values returned by the routine.


SPECIAL CONSIDERATIONS:

List of known bugs, caveats, etc.

7.3 Application Module Documentation

The documentation for LAS 7.0 is contained on-line in HTML (hyper-text markup language) format. NCSA Mosaic-2.0 for X is used as the document viewer via the lasdoc command. Every LAS function or module has at least one proc definition file (PDF) that contains the help for LAS procs. Except for the diagrams, the user guide information is kept in the PDF; the HTML file is generated from the PDF with the pdfhtml function. (Section 7.3.1)

LAS procs should keep all help directly in the PDF. The parameter names are based on a listing of standard parameter names for LAS and are agreed upon by the programmer and the LAS coordinator. The help is divided into two levels. The first level gives a brief description of the associated module and each parameter. Modules and parameters are discussed in detail in the second level help. The first sentence of the second level help is the first level help.

The parameters should be ordered so that all mandatory input files and specifications appear first on the screen, followed by mandatory output files and specifications, and then followed by any other mandatory parameters. Keep associated parameters grouped together as much as possible, especially any window specification. All required parameters should appear before optional ones.

The user documentation development can be quite complex. To help programmers maintain consistency, all documentation should be reviewed by several people. These reviewers should include lower level managers who are tasked with supervising the entire project and representatives of the ultimate users of the documentation, whether it be scientists or applications programmers. In addition, the pdfhtml function, which generates a HTML formatted file which then can be used by Mosaic-2.0 to generate a hardcopy user guide, assists the programmers in maintaining consistency. The following sections detail the accepted standards for using the pdfhtml function.

7.3.1 Pdfhtml Introduction

The pdfhtml function generates an HTML file directly from a PDF file. The programmer first creates the PDF as normally done and then adds the necessary information for a complete user guide by using a set of TAE comment directives. Pdfhtml reads the PDF file and determines which parts of the PDF belong in which sections of the corresponding user guide. Additional information for the user guide is determined from the TAE comment directives and text placed in the PDF.

There are several specific formatting considerations for the PDF file. These include things such as order, capitalization, spacing, and the TAE comment directives.

This document provides a listing of the TAE comment directives and their meaning, a skeleton PDF (to be used as a basic example) and a listing of user notes for pdfhtml and corresponding document examples.

7.3.2 TAE Comment Directives

The following is a list of the TAE comment directives used for the pdfhtml function. A skeleton PDF in Section 7.3.3 shows the usage of the primary directives. The user notes in Section 7.3.5 provide detailed examples for these and also for the remainder of the directives that are not shown in the skeleton PDF.

   !.HEADER	   Header and subsystem
   !.EXAMPLE(S)    Starts the Examples Section
   !.DESC	   Starts the Description/ Algorithm section.

    --The following directives pertain to error messages.

  !.NONFATALS	   Nonfatal Error Messages --for "None." or more than one
  !.NONFATAL	   Nonfatal Error Message --one nonfatal message
  !.FATALS	   Fatal Error Messages --for "None." or more than one
  !.FATAL	   Fatal Error Message --one fatal message
  !.ERROR	   Error Messages --No error messages and some statement 
                   is made
  !.USERNOTE(S)    Starts the User Notes section.
  .VAR "parm name-subcommand "Needed for parameter descriptions that vary 
                   with different subcommands 
		   Examples:
		      .VAR IN-SINGLE
		      .VAR IN-MULTI
  !.DYNLOCAL	   For dynamic parameter set within one pdf file
  !.FINAL	   End of text directive

    --TAE comment directives that pertain to formatting user guide

    !.FIG < figure >  Add a gif figure
    !.LINE         Add two blank lines
    !.LIST	   Used for formatting at the start of parameter responses
                   or a list
    !.LEND	   Used for formatting at the end of parameter responses 
                   or a list
    !.GOBBLE	   For inserting a comment to display in tutor mode but
                   ignored by pdfhtml

7.3.3 Skeleton PDF

    

  1.     !.HEADER Display

  2.     Process XXX HELP=*

  3. 

  4.     SUBCMD XXX

  5.     PARM XXXXXX

  6.     END-SUBCMD   

  7. 

  8.     SUBCMD XXXX

  9.     PARM XXXXXX

  10.     PARM XXXX

  11.     END-SUBCMD

  12. 

  13.     END-PROC

  14. 

  15.     .TITLE

  16.     Xxxxxxxxxxxxxxxxxxxxx

  17.     .HELP

  18.     Xxxxxxxxxxxxxxxxxxxxxxxxxxxx. Xxxxxxx

  19.     xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  20.     xxxxxxx.

  21.     .page

  22.     !.EXAMPLES

  23.     Examples:

  24.     1. LAS> XXX-XXX XXXXXX=XX XXX=XXX

  25. 

  26. 	   Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

  27. 

  28.     2. LAS> XXX-XXXX XXXX=XX

  29. 

  30. 	   Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

  31. 

  32.     .page

  33.     !.DESC

  34.     Description/Algorithm:

  35.     xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.  

  36.     Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  37.     xxxxxxxxxxxxxxxxx.  Xxxxxxxxxxxxxxxxx

  38.     .page

  39.     !.NONFATALS

  40.     Nonfatal Error Messages:

  41.     None.

  42.     .page

  43.     !.FATALS

  44.     Fatal Error Messages:

  45.     1. [xxx-xxxxx] Xxxxxxxxxxxxxxxxxxxxxx

  46. 

  47. 	   Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

  48. 

  49.     2. [xxx-xxx] Xxxxxxxxxxxxxxxxxxxxxxxx

  50. 

  51. 	   Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  52. 	   xxxxxxxxxxxx.  Xxxxxxxxxxxxxxxxx.

  53.     .page

  54.     !.USERNOTE

  55.     User Note:

  56.     1. Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  57.        xxxxxxxxxxxxxx.  Xxxxxxxxxxxxxxxx.

  58.     .LEVEL1

  59.     .SUBCMD XXX

  60.     Xxxxxxxxxxxxxxxxxxxxxxxxx

  61.     xxx

  62.     .SUBCMD XXXX

  63.     Xxxxxxxxxxxxxxxxxxxxx

  64.     .VAR XXXXXX

  65.     Xxxxxxxxxxxxxxxxxxx

  66. 

  67.     = XXX: Xxxxxxxxxxxxxxxxxxxx

  68.     = XXXX: Xxxxxxxxxxxxxxxxxxxx

  69.     	    xxxx

  70.     .VAR XXXX

  71.     Xxxxxxxxxxxxxxx.

  72.     .LEVEL2

  73.     .SUBCMD XXX

  74.     Xxxxxxxx(first level help)xxxxx. Xxxx

  75.     (second level help) xxxxxxxxxxxxxxxx.

  76.     Xxxxxxxx

  77.     .SUBCMD XXXX

  78.     Xxx(first level help) xxxxxx. Xxxxxxx

  79.     (second level help) xxxxxx.....

  80.     .VAR XXXXXX

  81.     Xxx(first level help)xxxxx. Xxxxx

  82.     (second level help)xxxxxxxxxxxxxxxxxx.

  83.     Xxxxxxxxxxxxxxxxxxxxxx.

  84.     !.LIST

  85. 

  86.       = XXX:  Xxx(1st level)xxxxxx. Xxxxx

  87.       (2nd level) xxxxxxxxxxxx.

  88.       = XXXX: Xxx(1st level)xxxxxxx. Xxxx

  89.       (2nd level) xxxxxxxxxxxxxxxxxxxxxxxxx.

  90.     .!LEND

  91.     .VAR XXXX

  92.     Xxx(1st level)xxxxxx. Xxxxx(2nd level)

  93.         xxxxxxxxxxxxxx.

  94.     !.DYNLOCAL xxxxx

  95.     .END

  96.     !.FINAL

7.3.4 Line Length/Margins for Formatting PDF and User Guide

The following is a reference for line lengths and margins.

  1. The left margin for responses should begin in column 3.
  2. The right margin for first level help should not exceed column 32.
  3. The right margin for responses should not exceed column 53.

7.3.5 PDFHTML User Notes and Instructions

  1. The !.HEADER directive on line 1 of the PDF generates the header "USER'S GUIDE" and the hardware specifics. The PDF must begin with !.HEADER and should contain at a minimum !.HEADER, .TITLE, and .HELP.

  2. The program name is placed after the Process or Procedure comment on line 2.

  3. SUBCMD and PARM must be in uppercase unless in an interval proc that is to be suppressed. Internal procs MUST use lowercase or pdfhtml will not run properly.

  4. The parameters for each subcommand must be between the SUBCMD and END-SUBCMD TAE constructs.

  5. The order of parameters as given in the declaration of the parameters at the beginning of the PDF must match the order that they are listed in the LEVEL2 section.

  6. The function description of the user guide is taken from text following the .HELP command.

  7. Examples, Error Messages, and User Notes must not extend past column 64.

  8. Do not have any blank spaces after directives such as !.EXAMPLES, !.USERNOTES, etc. The pdfhtml programs reads these and, as a result, the formatting is off.

  9. Do not leave any blank lines between parameter descriptions or between the "User Guide" sections. A blank line is allowed between the individual examples, the individual error messages and the individual user notes but not between the end of one section and the TAE commend directive for the start of the next section. In other words, a blank line is allowable between error messages themselves but not between the last error message and the !.USERNOTES directive.

  10. Each of the User Guide section headers -- !.EXAMPLES, !.DESC, !.NONFATALS, !.FATALS, !.USERNOTES -- must be followed with the respective header that it represents. (lines 33 and 34.) This second header is for tutoring in TAE. It is also necessary to put a ".page" before each section to provide a break for tutoring in TAE. (lines 32 and 42.) Use .page in the PDF file for other desired page breaks for "tutor mode."

  11. First level help must not extend past column 32 and the responses should be set up as indicated on lines 65 through 69.

  12. The help for subcommands in LEVEL1 and LEVEL2 must precede the parameter help and must be listed in the desired (correct) order.

  13. Parameter descriptions for the user guide are taken from the LEVEL 2 help from the PDF and the appropriate values for defaults are grabbed from the parameter declaration statement at the very beginning of the PDF or the parameter name is underlined automatically for those parameters that have no default. A null default value no longer has to be in the last place in the parameter declaration statement.

  14. If a diagram is needed in the hardcopy user guide and cannot be entered online, the !.GOBBLE and the !.FIG commands can be used to handle this for tutor mode and for the user guide. The !.GOBBLE commands can be used to insert a comment that displays in tutor mode indicating there is a diagram in the hardcopy user guide; the comment will be seen in tutor mode but not the hardcopy. The .!FIG command can then be used to designate a specific file for the diagram in the user guide.

    For example: 

    	1. LAS> XXXXXXXXX
	!.GOBBLE
	A diagram is available in the hardcopy user guide.
	!.FIG ../gif/file.name
  15. Generating a user guide from the PDF file:

        % pdfhtml sample 

    --The first parameter initiates pdfhtml.
    --The second parameter indicates the module.
       sample.html  file to be displayed with Mosaic-2.0
  16. Printing:

  17. Dynamic Parameters:

  18. Dynamic parameters are supported by use of the !.DYNAMIC command in the main PDF after the .VARS and before the .END. (See the skeleton PDF, in Section 7.3.3, for placement.)

  19. NAME= is NOT allowed.

  20. Each parameter definition must be on a separate line

  21. DEFAULT must be the last thing in the parameter definition

  22. A continuation mark "+" must be at the end of the line (PARAMETER and EXAMPLES). Any text or white space after a "+" will not be used as a continuation of the line.

  23. Numbered items (EXAMPLES, NONFATAL, FATAL, and USERNOTES) must start with a number in the first column.

  24. There must be white space (new line) between a number item and the items explanation. eg. the example and the explanation of the example.

  25. USERNOTES are number items and must contain white space (new line) between each item.

  26. LEVEL2 parameters that have valid options must start with !.LIST and end with !.LEND

  27. Any line between !.LIST and !.END must not exceed 74 characters

  28. MOSAIC and HTML ignore new lines and white space. Although this is the case, lines in the PDF should not exceed 80 characters including the new line.

  29. !.PAGE, !.PAGESUB, !.BLANK, and .PAGE, are ignored in PDFHTML

  30. !.GOBBLE ignores the next line in the PDF. The next line is not ignored in the TAE help.

  31. Remember,the PDF must look good in the TAE help session also.