BBjDocsGenerator Overview

In BBj 21.00 and higher, BBj includes a BBjDocsGenerator utility, which replaces the older BBjToJavadoc utility. The BBjDocsGenerator parses documentation blocks in object-oriented BBj program text, and creates API documentation from it. The generated documentation is in HTML format. It supports several command-line parameters that permit each run to be configured differently, permitting customized output from processing one or more BBj source files.

Documentation Blocks in BBj Source Code

BBjDocsGenerator will process either single or multi-line documentation blocks in a BBj program file.

• A single-line block contains a single line of BBj code that begins with REM /** that ends with */. The documentation block includes all of the text between the opening /** and the closing */.

• A multi-line block begins with a single line of BBj code that begins with REM /**. It ends with the next line of the form REM <optional text> */. The documentation block includes all of the text between the /** on the opening line and the */ on the closing line.

The BBjDocsGenerator identifies and processes description documentation blocks associated with:

• A package (at the BBj program file level)

• BBj classes (at the BBj Custom Object class level)

• BBj class fields (at the BBj Custom Object field level)

• BBj class methods (at the BBj Custom Object method level)

Tags in Description Documentation Blocks

BBjDocsGenerator will recognize and process some Javadoc-style tags that are present in documentation blocks. The following tags are supported:

In general, the text following one of these tags is free form. The individuals writing the code and adding the tags can include whatever information they choose. Therefore, it is important that they understand where their text will appear, who will see it, and when.

BBjDocsGenerator also supports markdown features in the documentation blocks, and applies those markdown instructions when it generates the output documentation.

Examples of Documentation Blocks

Some examples of documentation blocks can be seen in this BBj program code:

rem /**
rem * <code>Class MyFactory</code> - My Factory Class
rem * This class works as well as can be expected...
rem * @author J. X. LastName
rem * @version 1.0
rem */
class public MyFactory
...
  REM /** BBjNumber A - Our first field */
  field private static BBjNumber A
...
  Rem /**
  rEm * Constructor MyFactory
  REM * @see <a href = "https://documentation.basis.com/BASISHelp/WebHelp/bbjwindow.htm" target = "_blank">BBjWindow</a> for more details
  reM * @author A. B. SomeOtherLastName
  REM */
  method public MyFactory()
...
  rem /**
  rem * Method createNewFrame:
  rem * Instantiate a wizard frame
  rem * @param BBjTopLevelWindow Wizard window object
  rem * @param HashMap Common data map
  rem * @return BBjNumber Frame number
  rem */
...

Figure 1. Examples of Documentation Blocks

Specifying a Package in BBj Source Code

BBjDocsGenerator recognizes documentation blocks as the source of descriptions and details for the output documentation and supports one special instruction: a package specifier.

Defining a package at the top of a BBj Source File causes the documentation generated from that file to be organized into a package (or "namespace" with that name. For example, placing a single line of BBj code that begins with REM PACKAGE <NAME> at the top of your BBj source file tells the BBjDocsGenerator to group all of the documentation entries from this file into a single package named <NAME>. The <NAME> is white-space delimited (it is the first whole word encountered following REM PACKAGE).

Examples of Package Tags

Some examples of package tags can be seen below (where each block of text represents the text at the top of a different BBj source file):

File #1:

rem /**
rem * Optional package comments
rem */  
rem package main

File #2:

rem /**
rem * Optional package comments
rem */  
rem package main.sub1

File #3:

rem /**
rem * Optional package comments
rem */  
rem package main.sub2

Figure 2. Examples of Package Tags

Defining these packages at the top of three different BBj Source Files will cause BBjDocsGenerator to generate its documentation in a matching folder structure. In this example, the main folder would appear in the output directory, with sub1 and sub2 folders nested beneath it, like this:

<output folder>

+-- main

+------ sub1

+------ sub2

By using this model, you can organize your documentation output in a variety of ways.

Executing BBjDocsGenerator from a BBj Program

To generate documentation files for each of a list of BBj source files, call one of the BBjDocsGenerator.generateBBjdoc() methods in a BBj program such as the example program shown in Figure 3.

use java.util.ArrayList
use com.basis.bbjutilities.bbjdocsgenerator.BBjDocsGenerator
use com.basis.bbjutilities.bbjdocsgenerator.BBjDocsParameters

REM Tell BBjDocsGenerator where to put the output files
outputDir! = "C:\BBjDocsGenerator\MyFileDocs\"

REM Create a list of the file (or files) to process
prog! = "C:\temp\MyFile.bbj"
declare ArrayList list!  
list! = new ArrayList()
list!.add(prog!)
REM To process more than one file in a single execution, simply add more
REM   files to list! here

REM Instantiate the BBjDocsGenerator classes needed
declare BBjDocsGenerator generator!  
declare BBjDocsParameters params!  
generator! = new BBjDocsGenerator()
params! = new BBjDocsParameters()

REM Define optional parameters telling BBjDocsParameters how to run
params!.enableVerbose()

REM Tell BBjDocsGenerator to generate documentation for each file in
REM   list!, putting the output files in outputDir!, using the parameters
REM   in params! to control the output
generator!.generateBBjdoc(list!, outputDir!, params!)

end

Figure 3. A Simple BBj Program to Run the BBjDocsGenerator

In order to instantiate a BBjDocsGenerator and a BBjDocsParameters, BBj must be able to find definitions for those classes. These classes are defined in the BBjDocsGenerator.jar file that is installed in the <bbj_home>/lib folder beginning with BBj 20.30. For BBj to access that BBjDocsGenerator.jar file, you must first define a classpath that tells BBj where to find it. For this example, we defined a classpath named docs_generator in the Enterprise Manager as shown in Figure 4.

Figure 4. The docs_generator Classpath for the BBjDocsGenerator

When including the BBjDocsGenerator in a BBj program, use the -CPdocs_generator (classpath) argument to specify the classpath, along with USE statements similar to those shown in Figure 3.

Parameters for BBjDocsGenerator.generateBBjDoc()

There are two forms of BBjDocsGenerator.generateBBjdoc() available, as shown in the table below. Both take an ArrayList of strings as the first parameter (the list of one or more BBj source files to process), and a string providing the full path to the folder to hold the output documentation files as the second parameter. The third parameter is optional: a BBjDocsParameters object with one or more parameters set to control how the file(s) are to be processed. The simple BBj program in Figure 3 uses a BBjDocsParameters variable, params!, for that purpose.

Standard Parameters of BBjDocsParameters

Table 1: below lists the standard BBjDocsParameters methods that are available, and the effect of setting each one on the generated documentation files.

Table 1. The Standard BBjDocsParameters Methods to Customize the BBjDocsGenerator

Advanced Parameters of BBjDocsParameters

Table 2 below lists the advanced BBjDocsParameters methods that are available, and provides a high-level description of the result on the generated documentation files of setting each one.

Table 2. The Advanced BBjDocsParameters Methods to Customize the BBjDocsGenerator

You should not need to use these advanced methods, and thus a detailed explanation of how to use each method is not included here.

Output Files

After successfully running the BBjDocsGenerator, you will find that it created a collection of files in or under the folder you specified as the outputDir! argument to generateBBjdoc(list!, outputDir!, params!). For example, if you processed exactly one BBj program file, MyClass.bbj, that contained a comment setting the package as MyPackage and exactly one class named MyClass, you would see the following subfolders and files in outputDir!:

• allclasses.html

• allclasses-frame.html

• deprecated-list.html

• help.html

• Index.html

• index-all.html

• overview-frame.html

• overview-summary.html

• overview-tree.html

• script.js

• stylesheet.css

• class-use (folder)

  • MyClass.html

• MyPackage (folder)

• MyClass.html

• package-frame.html

• package-summary.html

The following sections examine the generated folders and files, and describe the contents of each.

Summary

BBjDocsGenerator creates an array of output files that together provide documentation that is suitable for your BBj Application Programming Interface (API). It relies upon the BBj program files containing a number of tags with accompanying description text to define the documentation it generates. The BBjDocsGenerator was created based on the Java concept of Javadoc API documentation. outlined in this document.