BBjToJavadoc Utility Overview


In BBj 12.0 and higher, the BBjToJavadoc Utility parses object-oriented BBj program text containing standard Javadoc comments to produce API documentation in HTML format automatically.

 

 For complete BBjToJavadoc documentation, click here.

 

Commenting the Source Code

See Commenting the Source Code in article The Java API Documentation Generator.

Example

rem/**
rem '* DialogWizardFrameFactory
rem '*
rem '* Dialog Wizard Frame FactoryClass
rem '*
rem '* @author R.Lance
rem '* @version 1.0
rem '*/

class public DialogWizardFrameFactory

    rem '/**
    rem '* Constructor DialogWizardFrameFactory
    rem '*/
    method public DialogWizardFrameFactory()
    methodend
    ...

    rem '/**
    rem '* Method createNewFrame:
    rem '* Instantiate a wizard frame
    rem '* @param BBjTopLevelWindowWizard window object
    rem '* @param BBjNumber Framenumber
    rem '* @param HashMap Commondata map
    rem '*/
    ...

Other often used directives include @see and @return.


Launch  the Wizard

From the Command Line

  1. Navigate to <BBjInstall>/utils/BBjToJavadoc.

  2. Execute BBjToJavadocWizardRun.bbj

From the BASIS IDE

  1. Open the IDE from BASIS > IDE.

  2. Locate the program file, right click, and choose [Generate BASIS Javadocs].

NOTE:If you have not yet mounted the directory containing the program file for which you are creating docs, be sure to File > Mount the directory inside the IDE.

 

Step 1 of 3: Select BBj source files

  1. Click  [Add file(s) to the list] to add BBj programs to be documented inside file open dialog.

  2. Set visibility scope option -

 

-->  Document only public classes and member

-->  Document only protected and public classes and members

-->  Document all classes and members

  1. Choose target document directory where the generated documents are to be saved.

  1. Verify your selections.

 

NOTE: To remove one or more files from the list, select the file(s) and click or choose to remove all files in the list. Click [Next] to proceed.

 

Step 2 of 3: Configure options

Choose from these selections:


INCLUDE

Author Text

Includes the @author text in the generated docs.

Version Text

Includes the @version text in the generated docs. This text is omitted by default. To see the version of your Javadoc tool, use the -J-version option.

"Use" Page

Includes one "Use" page for each documented class and package. The page describes what packages, classes, methods, constructors, and fields use any API of the given class or package. Given class C, things that use class C would include subclasses of C, fields declared as C, methods that return C, and methods and constructors with parameters of type C.

Note:This option only documents uses of the API, not the implementation. If a method uses String in its implementation but does not take a string as an argument or return a string, that is not considered a "use" of String.

Link to Source

Includes link declarations to lines in HTML copies of the program source code.

Detailed Messages

Includes more detailed messages while Javadoc is running. Without the verbose option, messages appear for loading the source files, generating the documentation (one message per source file), and sorting. The verbose option causes the printing of additional messages.

EXCLUDE

Comment Body

Excludes the entire comment body, including the main description and all tags, generating only declarations. This option enables re-using source files originally intended for a different purpose, to produce skeleton HTML documentation at the early stages of a new project.

Deprecated APIs

Excludes the generation of any deprecated API at all in the documentation. This does whatNo Deprecated List does, plus it does not generate any deprecated API throughout the rest of the documentation. This is useful when you are writing code and do not want to be distracted by the deprecated code.

"Since" Sections

Excludes the "Since" sections associated with the @since tags.

Javadoc Timestamp

Excludes the timestamp, which is hidden in an HTML comment in the generated HTML near the top of each page. Useful when you want to run Javadoc on two source bases and diff them, as it prevents timestamps from causing a diff, which would otherwise be a diff on every page. The timestamp includes the Javadoc version number and currently looks like this:
   <!-- Generated by Javadoc (build 1.5.0-internal) on Tue Jun 22 09:57:24 PDT 2004 -->

Deprecated API List

Excludes the generation of the file containing the list of deprecated APIs (deprecated-list.html) and the link in the navigation bar to that page. However, Javadoc continues to generate the deprecated API throughout the rest of the document. This is useful if your source code contains no deprecated APIs and you want to make the navigation bar cleaner.

Class Hierarchy Tree

Excludes the class/interface hierarchy pages from the generated docs. These are the pages displayed when pressing the [Tree] button in the navigation bar. The hierarchy is produced by default.

Index

Excludes the index from the generated docs. Default is with the index.

Help Link

Excludes the Help link in the navigation bars at the top and bottom of each page of output.

Navigation Components

Excludes the generation of the navigation bar, header, and footer otherwise found at the top and bottom of the generated pages. This option is useful when you are interested only in the content and have no need for navigation, such as converting the files to PostScript or PDF for print only.


Step 3 of 3: Generate documents

Check the [Show results] box to display the first page of the generated HTML document.

Press [Finish] to generate the API documentation process.


Example of the Output