Class Documentation

Name:DocCompiler
Version:1.0
ID:ID_DOCCOMPILER
Status:Unspecified
Category:Tool
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2001. All rights reserved.
Short:  Processes self-documenting source files from Rocklyte Systems.



Description

The DocCompiler class is designed to process source files that are self-documented using the Section Based Formatting standard from Rocklyte Systems. If you have seen source files from Rocklyte Systems before, then you may have noticed that all code is self documented within hash-marked areas. Take this example which documents a field named 'Apple':

  ##FIELD##
  Name:   Apple
  Short:  An apple a day keeps the doctor away.
  Type:   LONG
  Status: Read/Write

  ##DESCRIPTION##
  <p>This field tells you the total amount of apples that have been
  eaten by the object.</p>

  ##SEE ALSO##
  Field: Banana

  ##END##

If you look through some existing source files you will quickly gather an idea of how self-documented code works. The main advantages of writing documents in this way are: 1. Updating the documentation is easier because it is much 'closer' to the code. 2. The formatting can theoretically be processed into any other document type (currently HTML is supported, others may follow).

The purpose of this document is to describe how the DocCompiler class works, not to provide detail on the documentation standards used by Rocklyte Systems. Because a freely available application that uses the class already exists, there may be little point in creating a new application based on the class. However, you may find this document helpful for making modifications to that application (which is located in scripts:development/compilers/)

Actions

The DocCompiler class supports the following actions:

Activate  Processes source data into an output file.

Structure

The DocCompiler object consists of the following public fields:

Location  Set this field to the source directory or file location.
Output  Defines the object that will receive the text data.
Static  Set to TRUE to make the object static.
Action:Activate
Short:Processes source data into an output file.

Activating a DocCompiler object results in the file data being sent to the object specified in the Output field.

 

Field:Location
Synonyms:Src
Short:Set this field to the source directory or file location.
Type:STRING
Status:Read/Write

The location of the source files that are to be processed must be specified in this field. If there is only one source file that forms the document, you can set the exact location of the file to have it processed. If the document is split into multiple source files, you will need to specify the directory location so that each individual file is loaded and processed into one document.

Note that the validity of the location that you use is not validated until the DocCompiler object is Activated.

 

Field:Output
Short:Defines the object that will receive the text data.
Type:OBJECTID
Status:Read/Write

The Output field must be set so that a DocCompiler has an object to send its documented output to. If this field is not set, then the DocCompiler object will refuse to function.

The Output object must accept text-based information via data channels in order for the data to be interpreted correctly. If the Output object does not support text based information, the DocCompiler will still process the documentation but the user will not receive any text based output.

It is recommended that this field points to an object that is a member of the TextList class.

 

Field:Static
Short:Set to TRUE to make the object static.
Type:BOOLEAN
Status:Read/Init

By default, a DocCompiler object will execute itself and then self-destruct when a closing tag is received. If you would rather that the object stays in the system, set this field to TRUE. If you do this, the only way to get the DocCompiler object to perform is to call the Activate() action.