PVX-DOCS

What is it?

Java has Javadoc for generating the API documentation into HTML files from information in source code files. ProvideX now has PvxDoc which will allow the generation of class documentation from the source code of a ProvideX class definition.

This utility program was contributed by an anonymous third party. The original code was enhanced to allow it to be used as a contributed tool for the ProvideX plug-in for Eclipse. It will generate HTML documentation for all class files within a project (or directory tree). It will also identify any inheritance and sub-class relationships.

The plug-in API reference documentation was generated using this tool.

This document will provide a simple overview of the PvxDocs contributed tool. Additional information for creating and registering a new contributed tool is included in the 'Help Contents' for the ProvideX plug-in in Eclipse.

Configuration

This contributed tool includes a configuration program that can be used to control how the tool operates and the content and format of the output that is created.

Header Tags

This configuration panel identifies the header tags to be included in the documentation.

Configuration - Tags

Generation

This configuration panel is used to set the location where the documention will be created as well as header/footer logo images to be included in each file that is created.

Configuration - Generation

Sections

This configuration panel is used to control the order of the sections for each document that is created.

Configuration - Sections

Format

This configuration panel is used to set the format of the documentation to be created. It is also possible to produce HTML Compiled Help (CHM) files if the Microsoft HTML Workshop Help compiler (hhc.exe) has been installed.

Configuration - Format

Generating the ProvideX Class Documentation

Once the contributed tool has been registered, it will be available on the 'ProvideX / Contributed Tools' menu the next time that Eclipse is started.

The ProvideX Docs contributed tool requires that a resource in the source folder of a ProvideX project be selected; this resource can be the source folder or any resource in that folder (or a sub-folder). The PvxDocs tool is selected from the list of available tools and the "Run" button is pressed to begin processing the selected folder (and sub-folders) or resource.

Collection Class minimal documentation

The documentation will be placed into a 'pvxdocs' folder in the root of the project for the selected resource. Now, simply open the 'index.html' file that is in this folder to view the list of all class files that were processed. Select one of the class file names to view the documentation that was generated. When this tool is used with existing 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 a 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.

ProvideX Documentation Format

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.

There are two types of tags that are used by ProvideX Docs. The first group of tags is used to describe the build information for the resource. The second group of tags is used to describe the class definition. The next sections will itemize the tags within each group and describe how they are used.

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.
@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.
@Returns This tag is followed by the description of the returned value for the constructor or method.
@Value This tag is used to itemize fixed values that are used for parameters or returned values and explain the meaning of the fixed value.

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.
! ** ==>
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 will 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.
! ** @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
! ** @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.

Note:

All documentation for each tag should be grouped together; when the tag changes, the box surrounding the information will be closed and a new box will be started. This will force all documentation associated with each tag to be contained within the same box.

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.

Sample Source - *obj/collection.pvc

The following block of source code shows the class definition, including documentation:

! ** This is a generic collection object that will hold any numeric
! ** variable or object identifier.
! **
! ** This object simply holds object identifiers, the client class must
! ** manage the life span of objects added to this collection object.
! ** (I.E: call DROP OBJECT on each object identifier held in this 
! ** collection when the object identifier in no longer required)
! 
 def class "*obj/collection"
 	local ITEMTBL,ITEMALLOC
 	property COUNT write err
	! ** Add a new item to the collection.
	! ** @param ID The ID of the object to be added to the collection.
	function ADD(ID)ADD_ITEM
	! ** Return the object ID for the specified item in the collection.
	! ** @param index The position (or number) if the item to be returned.
	! ** @returns The object ID for the specified item in the list.
	function ITEM(index)=ITEMTBL[tbl(index>COUNT,index,-1)]
	! ** Delete an item, at the specified index, from the collection.
	! ** @param index The index of the item to be deleted from the collection
	function DELETE(index)DROP_ITEM
	! ** Find the index for the item that references the specified object ID.
	! ** @param ID The object ID to be located in the collection
	! ** @returns The index where the specified object was found in the collection.
	function FINDITEMBYID(ID)FIND_ITEM
end def

After the additional documentation has been added for each of the properties and methods, the PvxDocs can be used to process the folder (or resource) again. This time the HTML file that is produced will include the additional documentation.

Collection Class documentation

Sample Source - *obj/background_task_comm.pvc

The following block of source code is a portion of the documentation for the class:

! *obj/background_task_comm.pvc
! (c) Copyright 2006, Sage Software Canada Ltd. (Ontario, Canada)
! $Id: pvxdocs.html,v 1.1.2.2 2009/10/26 21:35:46 fred.mcguirk Exp $
/*
! ** This program can be used to assist with debugging in a background process on UNIX/Linux.
! **
! ** Start a listener in a new ProvideX process - this process will be "suspended" until
! ** the other task connects to the listener.  When using this class to assist with debug
! ** of a background process, it is easier to specify a name for the listener.
! **
! ** Add a line into the program executing in the background (or other) process to transfer
! ** terminal I/O to the listener process with the ID that is displayed on the listener
! ** screen.  You can then step through the code in the background process.  When
! ** complete, the connection to the listener must be broken so that normal processing can
! ** continue for both processes.
! **
! ** Steps:
! ** ==>
! ** Declare a new instance of this class
! ** Start the listener and optionally specify a name: %PvxCode(aTask=new("*obj/background_task_comm"); aTask'listenByName("DebugOne"))%
! ** Add line to background task program: %PvxCode(doDebug=new("*obj/background_task_comm"); doDebug'talk("DebugOne"); escape)%
! ** Step through the code in the background process.
! ** When complete, the connection to the listener must be broken.  The proper method for breaking the connection is to use the command: %PvxCode(doDebug'stop_Listener("DebugOne"); run)%
! ** <==
! **
! ** Do not forget to include the 'RUN' directive, otherwise the background process will
! ** be left in console mode and it will have to be killed.  An alternative method is to
! ** simply delete the lock file that has been created in the '/tmp' directory.  The file
! ** is named "pvx_lock_"+ID$.
! **
 */
def class "*obj/background_task_comm" unique create required delete required

This example shows the ProvideX code segments as well as the unordered list.

Collection Class documentation