./Source/robodoc.c

Docuwala/ROBODoc [ Modules ]

FUNCTION

ROBODoc is intended to be a replacement for the original AutoDocs program. ROBODoc will extract the comment headers from a source file, and put them into a separate documentation file. General Flow

      Sourcecode  ---> [ROBODoc] ---> Document.

The whole ROBODoc process consists of three steps: scanning, analysing, generating.

Scanning

ROBODoc scans the source directory tree. This collects the names of all the source files.

Analysing

ROBODOc analyses all the sourcefiles. This reads the content of all source files and collects all the headers.

Generating

In this step the headers are written to one or more documentation files. In addition

The data collected during scanning and analysing is stored in a number of structures.

RB_Directory, it stores the names of the sourcefiles and directories in the source direcory tree. File names are stored in a RB_Filename structure, directory names in a RB_Path structure. Each RB_Filename contains a pointer (path) to a RB_Path structure that tells in which directory a file is located. Each RB_Path has a pointer (parent) to another RB_Path structure that tells in which directory is a directory located (of which directory it is a subdirectory). The only exception is the root directory.

Besides the name of the sourcefile, the RB_Filename also stores the name of the documentation file.

For each sourcefile there is an RB_Part structure. It contains a pointer (filename) to the RB_Filename and a list (headers) of RB_Header structure containing the headers found in the sourcefile.

Every RB_Header structure contains a pointer (owner) to the RB_Part structure to which it belongs. Headers can form a hierarchy that is used to create sections and subsections in the documentation. To store this hierarchy every RB_header structure contains a pointer (parent) to its parent header. For instance, given the following two headers, SubModule is the parent of SubSubModule.

     ****h* TopModule/SubModule
     *
     ****

     ****h* SubModule/SubSubModule
     *
     ****

In the documentation this creates the sections

      1.TopModule
      1.1 SubModule
      1.1.1 SubSubModule

The RB_Directory and the linked list of RB_Part structures are stored in a RB_Document structure.

During the generation of the documentation ROBODoc tries to create cross links between the mention of a header's name (an object) and the documentation generated from that header (the documentation for the object).

To aid this proces there is an array of RB_link structures. This array is sorted for quick searching. RB_link structures the name of a header and the name of the label under which the documentation can be found in the documentation file.

AUTHOR

See AUTHORS in the archive.

CREATION DATE

20-Dec-94 Jacco van Weert.

MODIFICATION HISTORY

See ChangeLog in the archive. Latest version can be found on:

http://www.xs4all.nl/~rfsber/Robo/

BUGS

Other bugs? Catch them in a jar and send them to rfsber -(at)- xs4all.nl