Doc4GL documentation index page
The applications normally have three types of documents:
- structural specifications
- manual specifications
- documents for the users
The scope of this document is limited to documents that describe the applications structurally.
Documentation created in autonomous documents normally is obsolete and modified only when the management defines it as priority task (what usually only happens when we already don't have any resources available).
We think that the best way is to put programmers in charge of the documentation and place it close to the code that it's describing (or even in the source code).
Following the example of Javadoc, we decided to create a definite tool that on the basis of well defined standards extracts the information from the code and generates documents in specified format.
We must therefore try to follow this principles:
The structural documentation is defined in the form of documentation comments, written in the source code.
References of the changes in particular version of the programs must be kept in the versioning control system, like CVS or similar .
Who is the owner of the documentation comments - Designers, Documentation writers or Programmers ? The comments do not have to be of the exclusive responsibility of none of these entities. This is divided between them depending on the phase of the project.
It is important to notice that in majority of the projects, the programs source code is inherited and already exist, and in most cases is not documented. Or they are probably not documented in the format that we use or prefer.
Ideally, the documentation should be written by the programmers who implement or modify the functions. If there is a methodology for initial writing of a skeleton or prototype, and later each function implemented by the programmers, then the responsible person for the construction of the skeleton should write it.
When documentation effort is initiated after the application is already in use (in a process of redesign or to document it), must be FIXME efectuada under the form of taken over on a contract basis FIXME tentanto to the absolute maximum.
After the documentation comments are inserted, during the phase of maintenance of the project, the programmers have to modify all the documentation that relates to performed modifications. In the case of resolution of a bug, these must be registered in the version control instead.
These principles try to describe the comments for documentation. They must be understood as suggestions instead of rigid requirements to follow without question. There are always alternative ways, that if prove to be more efficient, should be used. Please suggest them to person responsible for this document.
Documentation Comments (doc comments)
Comments special written in the 4gl source code and delimited by {**... } symbols. These comments are processed by the p4gl tool to create the documentation in a relational database.
fgldoc
The tool that dynamically generates the documentation from the loaded data in the relationally formatted repository, inside the database system.
The tool generates documentation with origin in 4GL source files:
- Program source files written in 4GL language.
- Documents describing the business processes.
- Documents describing the packages.
Currently, form files (.per) menu files (.menu) and help files (.msg) are not processed by this tools.
A documentation comments are made from two parts: following description of zero or more tags, with a blank string between these sections:
{** This is the part of the description of the documentation comment @process SUBSCRIBERS }
- The first line is indented to be lined up with the code that follows the comment and starts with symbol of beginning-of-comment ({**) followed by one return (ENTER). FIXME: and what about the description as shown above?
- The following line start with an "*" or with a space. When it exist, the "*" is removed and substituted with a space (" ") character.
- A line of blank comment between the description and the list of tags must be inserted as shown above.
- To insert blank line between related tablets of tags....What? FIXME
- The ending line starts with symbol of end-of-comment (}) followed by one return character (ENTER).
Strings with more than 80 characters must be to be left (FIXME??). If there will be more than one paragraph in the documentation comment, separates the paragraphs with tag <P>.
First section (sentence)
The first section (sentence) of each documentation comment must be a summary, containing a concise but full description of the item that is to be described by the comment entry. The Javadoc tool uses this first phrase for the summary of the item. This becomes important for writing of summary information, that is easily recognizable.
This section (sentence) ends with the first full stop (".") followed by one of the following:
- space,
- tab,
- end of string
- or in first tag found.
In the following example, the first section finishes in "Prof." :
{** This is a simulation of experience of the Prof. Sparrow. }We can insert a full stop using HTML meta-characters to achieve this, as in following example:
{** This is a simulation of experience of the Prof. Sparrow. }
Following are some suggestions and conventions for writing of the descriptions in the documentation comments.
Use <CODE> for keywords and names
The reserved words must be surrounded by tags <CODE>... </ CODE> when included in a description. This includes:
- 4gl language reserved word
- Names of functions
- Names of variables (global, local and parameters)
- Examples of code
When mentioning function itself in the comment of the function, one must always omit the parentheses and the respective parameters. It is preferred to use the word method if you intend to use the function name.
Example:
- The function add allows to insert items. - Recommended
- Function add(item) allows to insert items - Avoid
Use expressions instead of full conjuncts, in the interest of the brevity
This rule must primarily be applied when you define tags, as for example the @param
Use third person (descriptive), not a second person (prescriptive) form
The description should be written in third, declarative person instead of second, imperative person.
Example:
- It returns the number: Recommended
- You return the number: Avoid
Descriptions of functions must start with verbal expression
A method implements an operation, thus normally starts with a phrase.
- Gets the name of the customer: Recommended
- This function gets the name of the customer: Avoid
Add descriptions beyond the name the function
The names of functions are automatically registered. However, if the comment repeats the name of the function, this does not add any information. The ideal comment goes beyond the these words and must always complement it with information that is not immediately (or at all) obvious from the name of the function.
Example:
Avoid -
{** * Affects the name of the customer *} function setClientName(name) ...Recommended -
{** * Stores the customer name in the modular variable and saves it in the table customers *} function setCliemntName(name) ...
Use "also known as" instead of "aka", or "to be more specific" instead of "i.e".
Optionally tags can be separated from the content/value with a column character:
@Author: John Smith
The : character will be removed from the documentation output.
Tags must be included in the following order:
@author @version @param @return @see @since @deprecated @todo @table (FIXME) for dynamic SQL statements that Doc4GL parser cannot automatically "see"
Tags on file (module) level only:
Tags accepted in both module and function level comments:
- @todo
- @author
Therefore, when writing a module level comment, that describes the 4Gl source file as the whole, user may utilize following tags only:
It is preferable to divide tags for related tablets.
When same tag is inserted multiple times, it must be separated from others to enhance readability.
Omit if author is unknown. FIXME: It can be used expansões efectuadas for the control of versoes. If several exist, it must be commanded for log order.
It can be used to expand the version control. It corresponds to the described item in source code, and not to the version of the executable that results from compilation of several source modules.
This tag must be followed by the name of the parameter (not it's type). Although it is redundant with the declaration of parameters, it is the only way to associate a comments with the parameter. For convention the first substantive of the description must reflect the type of information that it stores (it can be preceded by articles as " "). @param tag must have the same order as corresponding function parameters.
Example:
* @param num string formatting of the number * @param strUsing the number to formatDo not insert it between <CODE> </CODE> tags, because the scanning tool already creates them.
Preferably, use an expression in conjunction.
In functions that do not return any value, it must be omitted.
When the function returns different values, several tags for each occurrence of RETURN must be created.
Indicates a method as not to be used, to indicate it will probably be removed in next version.
It marks the version (when this is known ) from which the method was added.
Insert it only if this is known to be correct.
@todo
Defines a functionality to be implement in this method, in the future. It allows the programmer to mark task that must be implemented in the function, but that it is not opportune to implement at the moment, or only to note a problem or because it does not wants to break compatibility.
This way we can document what is lacking in implementation.
FIXME
@see
FIXME
@file
This DoxyGen sybmol is not needed, and will be ignored by Doc4GL
DoxyGen/JavaDoc list of tags: http://www.stack.nl/~dimitri/doxygen/commands.html
Also see doc/manager/FglDocumenter/test directory.
{** * This is a 4gl to test a 4gl import *} {** * Function comment * * @param a ParameterA * @param b ParameterA * @return Return a value *} function OneFunctionToTest(a,b) define a smallint define b char(20) return 1 end functionTO-DO - provide more examples
Doc4GL documentation index page Aubit 4gl project Aubit 4gl compiler documentation menu