What's in a Name
There are many parts of effective documentation in PowerBuilder. The first line of defense is object naming standards, many times I've looked at a project and seen objects named so badly even the developer cannot work out with datawindow goes with each window or the datawindow named the same as a different window. Make sure the object is named well! The next line of documentation is the library comments, effective use of the library comments can greatly aid development and help you instantly know what an object does. Be careful not to put too much information in the library description. Make sure the description does not scroll off the screen as its a pain to scroll to see the description and if your description is that long its too wordy! I've seen and tried to use strange single characters to give meaning and in practice it does not really help so stick to just a short description followed by a version number:

Order Entry V1.0
Product Maintenance Selection List V1.5

Object Comments
The next level of documentation is the object itself, this documentation describes the whole object in general. Place the object documentation in the same place for each object type:

Then use a common header for object documentation an example of an object header is shown below. The documentation is split into many sections, each section with a defined purpose. Note the documentation lines of text can span multiple lines and the maximum width of any line should not extend past the end of the rows of asterisks so that they print nicely with the default font.

/********************************************************************
   ObjectName: Object Short Description

   <OBJECT> Object Description</OBJECT>

   <DESC>   Event Description</DESC>

   <USAGE>  Object Usage.</USAGE>

   <ALSO>   otherobjs</ALSO>

    Date   Ref    Author        Comments
  00/00/99 ?      Name Here     First Version
********************************************************************/

• Use the OBJECT section to describe the overall object function, answer the question "What Does This Object Do For Me?".
• Use the DESC section to describe what this event does, this tells people reading your object what this event is all about. For example this event might aggregate other objects and initializes some variables.
• The USAGE section should answer the question "In General How Should I Use this Object?".
• The ALSO section provides a list of class names that might be used by this object, or who use this object, or might be of interest to people who are looking at this object.
• The version history provides details at the object level of all the changes that have happened to this object.

The strange tags surrounded by the greater and less than signs may seem strange but these tags allow documentation utilities to extract the information between the tags and produce documentation automatically for your objects. Like javadoc for java programmers. You can download a tool called PBDoc that uses these tags to produce professional quality documents. A text file containing this and other headers is available the free component page.

Function/Event Comments
Use the same script header to document all of your headers. My preference is to remove unused sections rather than just put none. The documentation tools that read your comments will realise that because it is missing and put none for you. The only exception to the rule is for the return value. I prefer to see that the script has no return value just by looking at the comment header. An example script header is shown below:

/********************************************************************
   FunctionName
        
   <DESC>   Description</DESC>
        
   <RETURN> Integer:
            <LI> 1, X ok
            <LI> -1, X failed</RETURN>

   <ACCESS> Public/Protected/Private

   <ARGS>   as_Arg1: Description
            as_Arg2: Description</ARGS>

   <USAGE>  How to use this function.</USAGE>

********************************************************************/

• Change FunctionName to be the camel case version of your function name.
• The DESC section should describe what this function does.
• The RETURN section should show the Datatype returned and the values that will be returned. The <LI> tags are used to display bullets in HTML.
• The ACCESS shows the visibility of the function
• The ARGS lists all the arguments in the sequence defined in the function followed by a colon, then a short description of what should be passed to the argument to the function. If there are no arguments remove the section.
• The USAGE should be a short one or two line code sample of what a sample call to this function would look like.

The strange tags surrounded by the greater and less than signs may seem strange but these tags allow documentation utilities to extract the information between the tags and produce documentation automatically for your objects. Like javadoc for java programmers. You can download a tool called PBDoc that uses these tags to produce professional quality documents. A text file containing this and other headers is available the free component page.

Automated Headers
One final note is that there are many tools on the market that will automatically build the comment headers for you. PBDR have a tool called PBPaste which you can download from this web site. Another tool is called XPound from Sapphire Software.