“Good code is its own best documentation" - - Steve McConnell
In most of the PLSQL documentation I have seen, large percentage of the information is trivial and is of minimal use in understanding the code. However many clients demand detailed level documentation to be provided along with the code delivery. Producing documentation for large PLSQL packages can be a tedious job.
The below method accepts a PLSQL package name (or filter with wild cards) as input parameter and produce an HTML output with the below information for each functions and procedures inside the package.
1. Name of the function/procedure
2. A description of the procedure which is stripped from any comment provided on top of the procedure/function.
3. List of parameters and types.
4. SQL statements used in the procedure/function
5. Dependendent tables and views used by the procedure/function.
Steps to generate the documentation
Step 1
Download and compile the PLSQL package.xx_plsql_doc
Step 2
Make sure that the dbms_output is on and the buffer size large enough. Invoke the procedure with the package name as the parameter value.
begin
xx_plsql_doc.generate('FND_USER_PKG');
end;
Alternatively, you can use a wildcard instead of the package name as parameter.
begin
xx_plsql_doc.generate('FND_USER%');
end;
Step 3
Save the HTML tags in Output window as a text file with .htm extension
Step 4
Open the .htm file using the browser. The output can be then copied to other applciations such as Microsft Word. The output for each ptocedure will be in the below format.
With this approach, we can produce consistent documentation across the project. I would suggest to edit the generated documentation to add information about any special logic which is used in the code.
