PLDoc User's Guide
by Andras Soltesz
PLDoc is a utility for generating technical documentation for PL/SQL packages. Working similarly to JavaDoc, it parses PL/SQL package specifications, finds comments of definitions and builds an 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:
It has an own PL/SQL package specification 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.
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.
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.
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).
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.
If you are using Windows, you may also use a convenience script for quick running of pldoc. This is named pldoc_drop.bat. Make a desktop shortcut of this .bat file, then drag-and-drop a SQL file on it. PLDoc will be run and the result shown in browser. This method is useful if you want to quickly try how a comment will look like in the documentation. You will find more detailed info in the pldoc_drop.bat file itself.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:
| Parameter name (and structure) | Description |
| -d <directory name> | The output directory's name. Optional, defaults to the current directory. |
| -doctitle <text> | Application name. Optional, defaults to MyApplication. |
| -overview <overview file name> | The name of the overview file we would like to include in
the main page of the technical documentation. Optional. |
| -nameslowercase | To convert all PL/SQL names to lowercase. Optional (by default the case is not changed). |
| -namesuppercase | To convert all PL/SQL names to uppercase. Optional (by default the case is not changed). |
| -stylesheetfile <filename> | CSS file to change style of the generated document.
Optional (using the supplied defaultstylesheet.css by default). |
| -definesfile <filename> | The file containing values for SQL*Plus variables.
Optional. |
| -inputencoding <enc> | Encoding used in the input files.
Optional (by default, assuming the operation system default encoding). |
| <file names | file name filters> | A list of input files and/or file name filters which define the exact
list of PL/SQL source files to be documented. Empty when generating from the Oracle dictionary, otherwise at least one file must be given. |
| -url <url> | Database url, for example jdbc:oracle:thin:@HOST:PORT:SID. Required when generating from the Oracle dictionary. |
| -user <username> | Schema name. Required when generating from the Oracle dictionary. The schema name is case sensitive since Oracle stores schema names like "My schema" (name with double quotes) as 'My schema' in the dictionary. Ordinary schema names like scott are stored as 'SCOTT' (upper case). |
| -password <password> | Password of the schema. Required when generating from the Oracle dictionary. |
| -sql <object name(s)> | Comma separated list of object name(s) to generate documentation for. Required when generating from the Oracle dictionary. An object name is case sensitive (the same rules as described for schema names apply). An object name may be prepended by a schema name and may have SQL wildcards. When the object belongs to a different schema than the logon user (as specified by the -user parameter), the logon user must have been granted the role SELECT_CATALOG_ROLE. |
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.
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;
There are three ways to place a package 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;
/
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;
/
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;
/
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
*/
FUNCTION check_partner(
id IN VARCHAR2
) RETURN NUMBER;
Keep in mind that @param tags should be placed in new lines.
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 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;
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
);
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.)
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
);
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.
The following files contain more information about PLDoc's current release:
readme.txt - important information about the current release.
changes.txt - changes in the software since the previous releases .