This guide provides you with the necessary information on how to write class and module documentation that is compatible with Rocklyte Systems documentation standards. This applies to developer related materials only - i.e. there is no official standard for documenting general information, although the use of HTML is recommended for user documents.
Although development documentation is distributed in HTML format, all code that is written by Rocklyte Systems is actually self-documented in a format that is referred to as "Section Based Formatting", or SBF. To create the class and module manuals, our source files are processed by a compiler that turns SBF compliant source files into HTML documents. This particular application - DocCompiler - is included with Athene under the development directory. You can see real-world examples of SBF source files just by viewing one of the existing source files on our web page. To see how it works, try processing one of these files through the DocCompiler and observe the output.
Writing self-documenting source code as opposed to writing raw HTML is helpful for a number of reasons, including:
Before you start writing documentation for your source code, it is recommended that you read the rest of this manual to ascertain the specifics of writing self-documenting source files. Without further ado, let us begin.
When documenting areas that include HTML formatting, you should try and limit the amount of HTML tags that you use. Keep it simple and try to avoid the use of tables and font changes. Under no circumstances should you attempt to insert JavaScript code or other non-HTML constructs into your documentation - in other words, keep it pure. Generally, you should be able to complete the majority of individually documented sections just by using the p, br, i, b and pre tags. Use of the a href tag is permitted if you need to refer to other web-sites or external documents.
The use of pictures and diagrams is permitted so long as files are stored in gif, png or jpeg formats. Pictures should serve as an aid to the documentation (e.g. for explaining something that is complicated), and must not be used for aesthetic purposes.
Bear in mind that when writing developer documentation you should treat it as a technical whitepaper, meaning it must be presented in a professional manner that is easy to read. Flashy presentation, changes in fonts and pretty pictures only serve as a distraction rather than an aid, so keep it simple and consistent.
It is recommended that you write documentation for your code once your progress is 50% towards completion. Do not document your code from the beginning as the most likely outcome is that you will need to re-write much of it at the end of your development cycle.
One of the main benefits of Section Based Formatting is that it allows you to spread your documentation throughout the entire source file, rather than writing it as a long stream of text. If your source code is split across multiple source files then that's no problem either, as the DocCompiler can read them all from the one directory if need be. Make sure that you take full advantage of this as it will make your life easier when making future updates to your code.
There are two different types of SBF source files - one style for modules and another style for classes. The type of documentation that you are writing is determined by the first mark, which must be either a Module or Class mark. This is followed by a set of definitions, all of which are optional but generally you will want to set the Name, Version, Date and Copyright information as a bare minimum. After that you can enter a description with the Description mark and add any important notes through the Note mark. In most cases you will then want to end the section with an End mark before documenting the functions and/or fields of the source code.
Let's look at this in more detail, starting with the header for a class document. In this example we have used all possible attributes for the class header and entered a description of the type of information you should enter for each attribute:
###CLASS### Name: The name of the class. Version: The version number of the class. ID: If the class has an ID then type it in here, otherwise enter 'Dynamic'. Category: The class should belong to a standard category - e.g. Command, GUI, Tool, IO or Effect. Available categories are listed in your system:classes/ directory. Include: If applicable, the include file for the class should be referred to here. Date: The month and year that this code was last updated must be entered here, e.g. 'February 2001'. Author: You or your company name should be entered here. Copyright: The copyright owner and the year of copyright must be specified here. Keywords: A comma-separated list of keywords can be listed in this attribute. Short: A short (80 character) description of what the class does can be entered here.
You should immediately follow-up the class header with a description of the class. Your description may contain HTML code, which should be organised into paragraphs. If necessary you can add any extra notes through a Note header, after which you should end the class header with an End mark. Example:
###DESCRIPTION### <p>The description of my class is entered here.</p> ###NOTES### <p>If I need to alert the reader through any notes, I can do so through this mark.</p> ###END###
If you are writing documentation for a module then the premise is much the same as that used for classes, but you will use a Module marker and slightly different attribute settings. This next example illustrates all of the available attributes for a module header:
###MODULE### Name: The name of the module. Version: The version number of the module. Date: The month and year that this code was last updated must be entered here, e.g. 'February 2001'. Author: You or your company name should be entered here. Copyright: The copyright owner and the year of copyright must be specified here. Classes: If the module includes one or more classes, enter a comma-separated list of all class names here. Keywords: A comma-separated list of keywords can be listed in this attribute. Short: A short (80 character) description of what the module does can be entered here.
Following the module detail you should enter more information using the Description mark and follow with an End mark, in the same way as we did for the class header.
If you are writing a class document then each field that forms part of the class structure must be documented. Fields are documented individually, starting with a Field header, then a Description, See Also mark and an End termination. Here is a descriptive analysis of the field header:
###FIELD### Name: The name of the field. Short: A short (80 character) description of the field's purpose. Status: Is the field Read, Write, Init, Read/Write or Read/Init? Prefix: If the field represents a lookup table or set of flags, there should be a prefix prior to each flag or lookup definition. Example: The prefix for FILE_READ is FILE. Type: The type of the field is specified here. Valid types are LONG, FLOAT, DOUBLE, STRING, POINTER, FLAGS and LOOKUP.
After following up the field header with a description, you have the option of adding a See Also mark. This mark is helpful for providing the reader with references to other documented areas that may be of relevance to the topic. Here is an example that refers to the XCoord and YCoord fields of the current class:
###SEE ALSO### Fields: XCoord, YCoord
Other valid See Also references are Function, Method and Action. If you need to refer to the documentation of another class or module, specify the name of the class or module, followed by a dot and then the reference. E.g. "Function: FileSystem.MoveFile".
If you are writing a class that implements one or more methods, they must be documented so that the developer knows how to use them correctly. If necessary, you may also document any actions supported by the class if you need to add clarification as to how they are supported. The Action and Method marks both use Name and Short definitions, while methods also require you to specify any additional arguments. Example:
###METHOD### Name: The name of the method. Short: A short description of the method's purpose. Arguments: The arguments used by the method must be specified in comma separated format, e.g. LONG Length, FLOAT Size.
The header must be followed with a Description, then Input, Result and See Also marks. For clarification on how to write Input and Result information, refer to the Documenting Functions section of this document.
If you are documenting a standard module interface then it is more than likely that you will be implementing one or more public functions. The definition for a standard function header is as follows:
###FUNCTION### Name: The name of the function. Short: A short description of the function's purpose. Synopsis: A C/C++ compatible synopsis for the function must be specified here, e.g. LONG RandomNumber(LONG Number).
After entering a description you will need to document the input parameters (if the function takes arguments) and the results of the function call. If the function was to take arguments named XCoord and YCoord for example, then the Input section would be as follows:
###INPUT### XCoord: Description for the XCoord argument. YCoord: Description for the YCoord argument.
You have two options for documenting the results section depending on whether or not the function returns an error-code. If the function is not returning an error-code then you can document the result of the function call using standard HTML code. On the other hand, if error-codes are returned then each individual error-code used by the function should be documented using a definition list. Example:
###RESULT### ERR_Okay: Description for this code. ERR_AllocMemory: Description for this code. ERR_InvalidDimension: Description for this code.
After documenting the function then you must terminate it with an End mark.
This is all the information that you need in order to write a valid self-documenting source file. If you want to know the specifics of how the DocCompiler class works, you can find the documentation for it on-line or in the class archive.
Next: Module Development Guide