Disclaimer: I am not a native speaker, so please forgive me for a large number of mistakes on the site

Pldoc - documentation generation tool for PL/SQL

2022-07-17

Pldoc ( Github mirror ) is a tool written in go which can generate html documentation for PL/SQL packages. It works only with packages source code and can’t handle triggers, stand-alone functions and object types.

Example of generated documentation

As an example, you can see how pldoc has generated documentation for the alexandria-plsql-utils.

GO TO THE DEMO

If you have any issues with pldoc, feel free to email me to ychbn@ychbn.com.

How it works

Pldoc was created under inspiration of how documentation is created in the Go programming language. I really like the idea of documenting code in a natural way, not writing directives like in javadoc. This way of documenting is more simple and what is more important, it doesn’t transform comments into unreadable mess. Compare this two comments:

-- Function get_user_acces returns
-- rowtype.
-- @param puser_id Users's id
-- @return usr_access%rowtype
function get_user_access(
    puser_id number
) return usr_access%rowtype;

-- Function get_user_acces returns
-- rowtype. Returns rowtype.
function get_user_access(
    -- User's id
    puser_id number
) return usr_access%rowtype;

In my opinion, the second example is more pretty - it looks natural; when you are writing code, you probably don’t want to switch thinking context just to remember which keyword you need to write to document parameter or function’s result or any other entity - you want to write comment in a human language for humans, not for another program which generates docs.

How to use

This command generates documentation for each file with .pks extension in the source_directory. The documentation files will be placed in the documentation directory. Note that only UTF-8 encoded files are supported:

pldoc --output=documentation source_directory

To change the extension of searched files, ext flag is used:

pldoc --output=documentation --ext=sql source_directory

Pldoc can generate docs from multiple directories, all you need is just list them with a space. Each directory will be walked recursively, for example:

pldoc --output=documentation source_dir1 source_dir2 source_dir3

Which comments are considered as documentation

Any comment that precedes an object (function, procedure etc). Here are some examples.

-- Returns true if the user has access to perform
-- this operation.
function has_permission(user_id number, op varchar2) return boolean;

If there is a blank line (or lines) between a comment and an object, the comment isn’t processed as documentation:

-- Returns true if the user has access to perform
-- this operation.

function has_permission(user_id number, op varchar2) return boolean;

However, an empty line (or lines) that is the part of a comment, isn’t taken into account as a separator between documentation and an object and a whole comment is parsed as documentation:

-- Returns true if the user has access to perform
-- this operation.
--
function has_permission(user_id number, op varchar2) return boolean;

There is only one way to apply formatting to generated documentation - indent content to represent it as a preformatted text, like this:

-- Procedure get_user_by_name returns an app_users row as its out
-- parameter. It can raise some exceptions in these cases:
--     1. User with specified name wasn't found
--     2. There are more that one user with specified username
procedure get_user_by_name(
    pname in app_users.username%type,
    prow  out  app_users%rowtype
);

In this case indented region will be wrapped in <pre> tags. It may be useful for lists and any preformatted text.

For now, pldoc can generate docs for:

Why not IDE tools

Because IDE plugins couple you with IDE itself. You can’t switch from SQL Developer to DataGrip or VSCode (which is ok for simple tasks with this extension). Another one reason is that you can’t automate documentation generation - you need open your IDE and perform necessary actions by hands.

Similar tools

Limitations