Need For Documentation

This document was created by the codedoc tool from a simple text-based set of document files and from embedded comments within the code. Some of the code is particular to this codedoc tool and some is part of the Information management library -- IMSLIB.

Once defined, the documentation specification is authored into an HTML form that can be viewed using a browser. The actual view consists of tabs across the top of the screen. Each tab has a set of pages that are listed in the left column of the screen. Each page can have a set of topics that are listed under a Table of Contents at the top in the right column of the screen. Finally, each topic can have a set of subtopics associated with it that are listed at the bottom of the text for the topic.

This tab describes the use of the documentation capability and the code base that implements it.

Documentation Commands

Documentation Command

The attributes of the Documentation command are as follows:

 <Documentation id="pBasic" filename="docum.bnd"/>
    <Include Filename="Introduction.xml"/>
    <Include Filename="CommandLine.xml"/>
    <Include Filename="Configuration.xml"/>
    <Include Filename="Prototypes.xml"/>
    <Include Filename="Runtime.xml"/>
    <Include Filename="lpslib.xml" />
    <Include Filename="imslib.xml" />
 </Documentation>

To review topics discussed elsewhere as well, the initial tag Documentation is accepted by the main entry point of the Document capability. It identifies the overall purpose of this specification file. Obviously, the closing tag must match it. Also all the included files must also use the same initial and closing tag. This ties these files together and reduces the likelihood that one of the included files might be used in the wrong context.

This file is processed in the same manner as any other "XML script". Below is the listing of the "make.bat" file in the "source" subdirectory of the documentation being viewed that processes the above.

  del *.bnd
  CodeDoc pBasic.xml site=c:\gmTools\site

The "docum.bnd" file, specified on the Documentation command, Contains the individual html files making up the authored documentation in bundled form. Note that the site= command-line switch specifies the pathname to which the actual documentation will be deployed. Thus, the first few cat commands in this file look as follows.

 cat >c:\gmTools\Site\pBasic.html <<'!)(!'
 cat >c:\gmTools\Site\border_left.html <<'!)(!'
 cat >c:\gmTools\Site\Introduction_Header.html <<'!)(!'

The unbundling or "deployment" of the documentation is performed by the deployment tool. In this case, the actual tool invocation would be as follows.

 deploy docum.bnd REPLACE

The above is the listing of the "makesite.bat" file in the source subdirectory of the documentation being viewed.

Document Command

<Document id="document" label="Documentation"
          title="Deployimng Documentation"
          tooltip="Description of Documentation Production"
          href="Document_Index.html"
          header="Document_Header.html"
          body="Document_Body.html"
          navigation="Document_Navigation.html"
          type="buttons" height="36" width="120"
          stylesheet="promula.css"
>

To begin, notice that the colored tab of the current display is "Documentation" which is the label specified above. The labels on the other tabs are the labels of the other documents in this set. The order of the tabs is the order in which the documents were defined within the documentation. The browser reports the filename being viewed as "Document_Index.html" which is the href attribute above. Placing the mouse over the Document tab displays the tooltip "Description of Documentation Production" which is the tooltip. The left side of the display Contains a series of "buttons" which are 36 pixels high. The left side display overall is 120 pixels wide -- all as specified above. The actual button labels are obtained from the page commands that are contained within this document. They are described below.

In general, documentation is viewed as a two-dimensional display, where the documents make up the first dimension across the top and the pages within the document make up the second dimension down the left side.

As with the Documentation command note that documents themselves contain no explicit content. They are organizational units.

In addition to the navigation type buttons there is the navigation type anchors. This type simply uses simple strings that can be selected. It is used when there are a large number of pages within a given document.

Page Command

Topic Command

Subtopic Command

Code Command

 <code dir="\gmTools\codedoc">
    authordocumentation.c
    authorhtmlsource.c
    ...
 </code>

There is no limit on the number of source code files that may be included in a given Code command.

Though they vary somewhat depending upon the implementation language each source code entry-point description contains the following parts:

1. Title -- Short description
2. Synopsis
3. Description of Service
4. Properties of Service
5. Return Value of Service

The title part gives a brief description of what the entry-point is. These title sections also appear in the table of contents. Hopefully, the descriptions are sufficiently clear that a developer looking for some capability can at least find possible candidates by browsing the table of contents.

The synopsis part shows exactly how the entry-point is called -- its type, its argument types, and what include files or packages are needed to validate its reference. This part also has a brief description of each argument. This is also the only part of the entry-point description that is language specific.

The description part attempts to explain exactly what service the entry-point provides. This can be very long or can be very short -- when the service performed is obvious from its short description. In general, each description is made as complete as possible with as little cross-referencing as possible. Again the assumption is made that this documentation is primarily intended for reference. It is not the great American novel.

The properties part describes exactly what characteristics each entry-point argument has with relation to the service being performed. These descriptions are made as complete as necessary and are made as implementation language independent as possible. Ideally, all language specific information about the entry-point is restricted to the synopsis -- but we can do no better than to strive towards ideals.

Finally, the return part describes what values, if any, are returned to the caller by the entry-point as a result of performing the service.

These entry-point descriptions are bound by ;/doc/ **** records, as shown in the example below

    /*
    ;/doc/ ***********************************************************************
    ;
    ; DocSourceError: Issue Source Code Documentation Error
    ;
    ; void DocSourceError                  Issue source code documentation error
    ; (
    ;    int   errNumber                   Specifies number for the error
    ;    char* message                     Specifies message for the error
    ; )
    ;
    ; Description of Service:
    ;
    ; This service issue an error message when the source code documentation
    ; processor detects a problem.
    ;
    ; Properties of Service:
    ;
    ; errNumber        This integer contains the unique number that identifies
    ;                  the error.
    ;
    ; message          This string contains a message describing the error.
    ;
    ; Return Value From Service: None
    ;
    ;/doc/ ************************************************************************
    */

Content Command

The two margin characters that are recognized are '|' and '/'. The bar indicates that the lines are to be entered into the HTML page exactly as they are entered in a fixed font. The slash, when associated with a line, forces a line break.

In addition to annotations, text is also searched for lines ending in a colon. Such lines are assumed to introduce lists of some sort that receive special HTML tags to make them standout. There are four types -- Ordered_text, table_list, unordered_list, and unordered text.

Ordered_text is initiated when the first line non-blank line following a line ending in a colon begins with a numeric character. The entries may have multiple lines which are identified via a secondary margin.

Table_list is initiated when the second line after a line ending in a colon starts with a minus sign. The entries may have multiple lines which are identified via a secondary margin.

Unordered_list is initiated after a line ending in a colon and neither of the above criteria are met and there are no blank lines in the list range.

Unordered_text is initiated after a line ending in a colon and none of the above apply.

Tool specific Processing

Documentation Storage Structures Used

The tDocTopic structure and tDocCode which extends it contain the actual content of the documentation. This content can be a main topic, a subtopic, or derived code documentation.

The tDocument Structure

The tDocPage Structure

The tDocTopic Structure

The tCodeDoc Structure