ProvideX Class Documentation - Write Documentation

When this tool is used with class source files that have not been modified to use the new PvxDoc document tags, it will generate documentation that includes only the property and method declarations for the class.

Collection Class minimal documentation

The remainder of this document will explain how to use the new PvxDoc tags and documentation formatting to add more information into this class definition.

Document the Class Definition

The placement and ordering of the documentation and tags within the source file is very important. All tags for the class, a property or a method must immediately precede the declaration. The documentation lines that do not include a tag are used to describe the class, property, or method.

The description of the class and the definition of the constructor for the class must be before the DEF CLASS statement. If there are arguments to be passed to the constructor, these must be described after the '@Constructor' tag and before the DEF CLASS statement.

Adding Documentation to Source Files

The documentation is placed into comment (remark) lines in the source file. All of these lines must begin with "! ** " or "! *- " and can be followed by an optional tag and then the documentation text.

Any lines that are placed within C-style block comments (starting with "/*" and ending with "*/" and spanning one or more lines of text in the source file), or that begin with "! *- ", will not be included in the tokenized program.

Tags to Classify / Organize Documentation

There are several types of tags used by ProvideX Docs. Each is described in detail in the following sections.

Build Information Tags

The build information tags are optional. If they exist in the source code (within the first 25 program lines), these tags will be used to update the build properties for the resource. When the properties are modified on the resource's properties page, the information for the corresponding tags will be automatically updated in the source file.

The build tags should be grouped together near the beginning of the source file. These tags can be used with any ProvideX source file and are not restricted to class definitions.

The build information is used when building the program from the source code. This information also includes the author and original date of creation for the program.

Tag	Description / Usage
@Author	The original author of the program. This value is not used by the build process.
@Date	The date when the original program was completed. This value is not used by the build process.
@Flags	The flags that are used during the build process to allow a developer to associate the program with special flags that are part of the system activation code.
@ForceLineNumbers	This boolean value (true or false) is used by the build process to determine if line numbers are to be forced for the tokenized program.
@LineNumberInc	This numeric value (1 - 25) is used by the build process to determine the line number increment to be used for the tokenized program.
@Outputfile	The name of the output file to be created by the build process.
@Owner	The owner code is used by the build process to allow a developer to assign a special code to the program.
@Password	A password that will be used to encrypt the program during the build process.

Class Definition Tags

The class definition tags are used to document the external interface to the class.

These tags are placed within the class definition section of the source file. Any documentation tags that are placed after the 'END DEF' are ignored when generating the HTML files.

Tag	Description / Usage
@Constructor	Explain the actions performed by the constructor for the class. This tag is followed by the text that describes the constructor. The explanation can span multiple lines in the source file - only the first line is required to use this tag; the documentation will continue until another tag is used or the DEF CLASS statement is encountered. When there are arguments that are required for the constructor, these will be described using @PARAM tags following the constructor documentation.
@Note	Document special information about a property that must be highlighted to draw the attention of the reader.
@OList	Start an ordered list. each item in the list must be on a separate line start a line with a '+' character to add to the previous line a blank comment line in a list will be ignored the list ends at the next tag or the end tag for the list (@OList_End or @UList_End).
@Param	Defines a parameter for the class constructor or a method. This tag is followed by a variable to identify the parameter and then an explanation of the argument. Start the parameter description text with a '+' character to add to the previous line.
@Returns	This tag is followed by the description of the returned value for the constructor or method.
@Type	This tag is followed by the description of the data type of a property value.
@UList	Start an un-ordered list. each item in the list must be on a separate line start a line with a '+' character to add to the previous line a blank comment line in a list will be ignored the list ends at the next tag or the end tag for the list (@OList_End or @UList_End).
@Value	This tag is used to itemize fixed values that are used for parameters or returned values and explain the meaning of the each value. The tag should follow the parameter or return value that uses the values. Each value is described on a separate line. All values will be grouped together into a table. To add a heading to the table, use a description starting with heading= as the first value in the list.
@Warn	This tag is followed by text to be placed into a warning box and can be associated with the documentation for the constructor, a property, or a method.

Special Substitution Tags

The following substitution tags are used to standardize the references to other classes.

%JavaClass(<class_name>)%: Highlight a reference to a Java class definition and generate a link to the documentation for the class.
%PvxClass(<class_name>)%: Highlight a reference to a ProvideX class definition and generate a link to the documentation for the class.
%PvxLibClass(<lib_class_name>)%: Highlight a reference to a standard ProvideX class definition (included in the ./lib folder of the distribution) but do not generate a link to the documentation for the class.

Formatting Tags

The following substitution tags are used to format the information in the final document.

%PvxCode(<ProvideX code example>)%: Special formatting for a ProvideX code segment; code segment on new line.
%PvxCode2(<ProvideX code example>)%: Special formatting for a ProvideX code segment; code segment will replace tag in same line.
%PvxCodeBegin% / %PvxCodeEnd%: Special formatting for a multiple line ProvideX code block; spacing and line breaks are preserved.
! ** ==>: Begin an unordered list of information. Each if the lines that follows will be a new item in the list.
The list will end at the next line that is either '! ** ' or '! ** <==' .

Documentation Lines

The following definition table shows the different types of documentation lines that can be used for a class definition.

! ** @Constructor: Document the constructor for the class. If this documentation is too long for a single line, each additional line does not use the '! ** @Constructor ' tag.
! **: Document the class, property or method. There may be multiple '! ** ' lines for a long or detailed explanation.
! ** @Note <text>: Include a notice within the documentation for a function. This notice will have a light grey background so that it will stand out from the other documentation for a function.
! ** @OList: Begin an ordered list; end the list with the '@OList_End' tag.
! ** @Param <var>: Document the arguments for the constructor or method. Each argument is described on a separate line.
! ** @Returns <text>: Document the value returned by the constructor or method
! ** @Type <text>: Document the data type of a property
! ** @UList: Begin an unordered list; end the list with the '@UList_End' tag.
! ** @Value <value>: When a parameter or the return value can be one of several fixed values, these values can be documented using this tag. The tag should follow the parameter or return value that uses the values. Each value is described on a separate line. All values will be grouped together into a table. To add a heading to the table, use a description starting with heading= as the first value in the list.
! ** @Warn <text>: Add a warning block into the documentation for the constructor, a property, or a method.