PLDoc User's Guide

by Andras Soltesz

Overview

PLDoc is a utility for generating technical documentation for PL/SQL code. Working similarly to JavaDoc, it parses PL/SQL packages, object types, functions, procedures, and triggers, finding comments of definitions and building HTML format technical documentation for your project. By using it, ORACLE database developers will have better documented projects and more consistent documentation.

Main features of PLDoc:

• Uses its own PL/SQL code parser to analyze PL/SQL definitions.

• Builds a structured, XML database from the definitions.

• Generates the HTML documentation by using Xalan and XSLs so customization of the output can be easily done.

General

When we refer to a command file used on Windows systems (e.g.: pldoc.bat) always keep in mind that a similar operation is possible with the shell script created for UNIX systems (pldoc.sh). In order to avoid repeating ourselves in the documentation we only include the operation with the file having the .bat extension.

Installation

After you have downloaded the binary release of PLDoc as a compressed ZIP file:

1) Install Java runtime version 1.2 or above, if not yet installed (available from JavaSoft).

2) Unpack the compressed ZIP into a new directory. (This will be PLDoc's home directory)

To use PLDoc with its standard settings you have to have the java runtime interpreter in your path.

After having installed PLDoc, read through readme.txt and changes.txt to learn more about the current release.

Running the sample project

You can run the sample project to test the installation or to see an example of the work results of PLDoc. To start the sample project run pldoc_example.bat.

The sample project's PL/SQL packages can be found in the \samples directory. You can examine these package definitions to see working examples of the comment formats PLDoc accepts.

The generated documentation can be found in the SampleApplicationDoc directory (only after you have run the sample project). The XML database containing the parsed PL/SQL definitions is located here as well (application.xml).

Using PLDoc

The easiest way to use PLDoc for your project is to make a copy of pldoc_example.bat and edit the new file. The example file does a parameterized call of pldoc.bat, which is responsible for more complex environment settings (e.g.: classpath) and starting the Java application itself.

Starting pldoc.bat is possible from a directory different from PLDoc's home directory, so your customized command file, starting from a different directory, doesn't have to programmatically enter PLDoc's directory before you call pldoc.bat. 

PLDoc's runtime parameters

An few example calls of the pldoc.bat command file:

call pldoc.bat -overview samples/overview1.html -d SampleApplicationDoc samples/sample*.sql

call pldoc.bat -url jdbc:oracle:thin:@localhost:1521:ORCL -user SCOTT -password TIGER -sql SYS.DBMS_PIPE,SYS.DBMS_OUTPUT

The parameters we can use when running PLDoc:

Commenting rules

There are some rules which you have to adhere to in order to provide PLDoc conform comments. There are comment types used by PL/SQL developers which are not currently supported by PLDoc.

In general, the same rules apply for writing formal comments as for javadoc. At the moment PLDoc supports only the following tags: @headcom, @deprecated, @param, @return and @throws. If you do not have time to read the javadoc rules, at least keep in mind the main highlights:

• The comment text will be treated as HTML. You can use HTML tags, formatting, links etc. If you need a line break in the text, put a <br/> tag.

• The first sentence of the comment (ending with a dot) becomes the "summary" for the comment, shown in the Summary part of the generated documentation.

• All tags (if any) must be placed after the main comment text.

Formal, informal comments

Although PLDoc supports some types of the informal comments (single line --, /* */), try to use formal comments everywhere in your code ( /** ... */). Special PLDoc comment tags (e.g.: @param) can be used only in  /* ... */ and /** ... */ (multi-line) comments so if you want to take advantage of PLDoc's more advanced features you have to review your code for correcting multi-line -- comments.

PLDoc accepts the following two comment types:

/* Checking the partner record whether it exists or not */
FUNCTION check_partner(id IN VARCHAR2) RETURN NUMBER;

/** Checking the partner record whether it exists or not */
FUNCTION check_partner(id IN VARCHAR2) RETURN NUMBER;

and accepts this as well:

--Checking the partner record whether it exists or not
FUNCTION check_partner(id IN VARCHAR2) RETURN NUMBER;

but doesn't accept  this:

--
--Checking the partner record whether it exists or not
--
FUNCTION check_partner(id IN VARCHAR2) RETURN NUMBER;

The package/object/collection comment

There are four ways to place a package, collection, schema-level function or procedure comment. The result will be exactly the same in all cases. Whichever you choose, it must be a formal comment.

The first method is to put the package comment text immediately before the package code:

/** 
*========================================================================<br/>
* A package for handling partner related activities like
* (adding a new partner, updating partner data, removing a
* partner)
*/
CREATE OR REPLACE
PACKAGE PARTNER_ACTNS
IS
...
END;
/

This method has a disadvantage when running PLDoc against a database: the comment is not saved with the source code.

Next method is to put the package comment text immediately before the IS keyword:

CREATE OR REPLACE
PACKAGE PARTNER_ACTNS
/** 
*========================================================================<br/>
* A package for handling partner related activities like
* (adding a new partner, updating partner data, removing a
* partner)
*/
IS
...
END;
/

This method should not be used to document schema level functions and procedures; PLDoc requires that the comment is before the parameter list

Next method is to put the object comment text between the object type and the object name:

CREATE OR REPLACE
FUNCTION
/** 
* Retrieve name from supplied ID.
* * @param p_id Person ID
*/
FN_GET_NAME ( p_id INTEGER) RETURN VARCHAR2 IS
...
END;
/

This method has the advantage that comments are retained in the database, and may be extracted from compiled objects using PLDoc. This is the only practical way of adding effective PLDoc comments to collection, schema-level functions or procedures.

And the last method is to put the package comment anywhere between the IS and the END keywords of the package spec (but not inside the functions/procedures of the package). In this case, you must add the @headcom tag to the end of the comment text, to distinguish the package comment from comments for functions/procedures.

CREATE OR REPLACE
PACKAGE PARTNER_ACTNS
IS
/** 
*========================================================================<br/>
* A package for handling partner related activities like
* (adding a new partner, updating partner data, removing a
* partner)
* @headcom
*/
...
END;
/

The parameter descriptor comment (@param)

PLDoc supports the @param tag (well known for Java programmers) but doesn't support -- comments placed after parameter definitions.

Not accepted by PLDoc:
/** Checking the partner record whether it exists or not */
FUNCTION check_partner(
    id IN VARCHAR2 -- The ID of the partner we want to check
) RETURN NUMBER;

Accepted by PLDoc:
/** Checking the partner record whether it exists or not.
* @param id The ID of the partner we want to check
* @return Full Name of the Person
*/
FUNCTION check_partner(
    id IN VARCHAR2
) RETURN NUMBER;

Keep in mind that @param tags should be placed in new lines.

The deprecated state comment (@deprecated)

You can mark PL/SQL entities deprecated by using the @deprecated tag. You can place this tag at the end of the multi-line comment providing some information together with the mark (e.g.: what should be used instead of the entity)

/** Checking the partner record whether it exists or not.
* @param id The ID of the partner we want to check
* @deprecated Use something <b>new</b> instead.
*/
FUNCTION check_partner(
    id IN VARCHAR2
) RETURN NUMBER;

The return value comment (@return)

The return comment can be used to describe the return value of a PL/SQL method. Usage:

/** Checking the partner record whether it exists or not.
* @param id The ID of the partner we want to check
* @return 1 if the partner exists, -1 if it doesn't.
*/
FUNCTION check_partner(
    id IN VARCHAR2
) RETURN NUMBER;

The thrown exception tag (@throws)

Specifies the exception the method throws. Usage:

/** Thrown when a partner would be necessary for the operation
* but it cannot be found */
NO_PARTNER_FOUND EXCEPTION;

/** Removes the partner
* @param id The id of the partner to remove
* @throws NO_PARTNER_FOUND If the partner cannot be found
*/
PROCEDURE remove_partner(
    id IN VARCHAR2
);

Using line breaks and HTML tags

Since the output of PLDoc is an HTML format documentation it is possible to use HTML tags in the comment text bodies to get better formatted output. Comment text is treated as HTML but only well-formed XHTML tags are allowed (you must use <br/> instead of <br>) etc.)

Placing @ tags AFTER the comment text

Sections with @ tags should always be AFTER the comments. For example: If we are commenting a procedure and its parameters we always write the comment of the procedure first and we start the @param tags after the comment text of the procedure.

/** Removes the partner and its dependent objects (cascading delete is set on this table)
* @param id The id of the partner to remove
*/
PROCEDURE remove_partner(
    id IN VARCHAR2
);

SQL*Plus Variables

It may be the case that your code contains some SQL*Plus variables (like &myvar). If they do not affect PLDoc, you may leave them as is. But in case PLDoc cannot parse the code (e.g. some language constructs are substituted by variables) you can specify values for substitution.

To do this, create a text file containing the names of variables (with leading &), and the values, separated by '='. Each assignment should be on separate line. For example, if you want to substitute value "first value" for variable &myvar1 and "second value" for variable &myvar2, create a file with the following content:

&myvar1=first value
&myvar2=second value

Next, when you run PLDoc, add a command line parameter to point to the file:

call pldoc.bat -definesfile mydir/myvariables.txt <...>

PLDoc will replace all occurrences of &myvar1 and &myvar2 in the PL/SQL files with their respective values. After that, documentation will be generated as usual.

Additional information

The following file contain more information about PLDoc's releases:

Change Log - changes in the software since the previous releases .