Skip to content

Latest commit

 

History

History
executable file
·
372 lines (290 loc) · 8.36 KB

javadoc.md

File metadata and controls

executable file
·
372 lines (290 loc) · 8.36 KB
Raw

JavaDoc for PL/SQL

This document outlines all the JavaDoc options for PL/SQL as well as examples on how to reference them in a template.

Intro

JavaDoc is a documentation notation created for Java applications. It can also be extended to other programming languages, in this case PL/SQL. The standard format for JavaDoc comments is:

...
/**
 * Comments about a procedure or function
 *
 * Some tags (using the @tag notation)
 * @param p_x description of variable x
 * @param p_y description of variable y
 */
procedure some_proc(p_x in varchar2, p_y in varchar2)
...

For more examples of JavaDoc check out the OOS-Utils project.

Ignore

Blocks of code can be ignored by using /*! instead of /** to start the block of documentation. If a block of code is ignored it won't be available for the template to process. Example:

/**
 * Not ignored.
 */

/*!
 * Ignored.
 */

Tags

@author

@author <author name>

Example:

/**
 * ...
 * @author Martin Giffy D'Souza
 * ...
 */

Template Reference:

Author: {{author}}

Result:

Author: Martin Giffy D'Souza

@created

@created Is used to note the date the method was created.

Example: see @author

@example

This tag allows you to include a full multiline example of your code along with any results.

Example:

/**
 * ...
 * @example
 *
 * select *
 * into l_temp
 * from dual;
 * ...
 */

Template:

{{#if example}}
### Example
```plsql
{{{example}}}
```
{{/if}}

Result:

### Example
```plsql
select *
into l_temp
from dual;
```

@issue

@issue <number> <description (optional)>

The @issue tag is used to reference multiple main issues for a give method. If a hash (#) is prefixed to the issue number it will be removed from the issue. The reason it is removed is that most references to the hash are for GitHub or Bitbucket purposes. They don't work for links as the hash will be considered as an anchor tag.

Example: Note: the leading hash does not matter

/**
 * ...
 * @issue #12 Initial creation
 * @issue 23 Some major update
 * @issue 46
 * ...
 */

Template Reference:

{{#if issues}}
### Issues
Issue | Description
--- | ---
{{#each issues}}
[{{number}}](/issues/{{number}}) | {{description}}
{{/each}}
{{/if}} {{! issues}}

Result:

### Issues
Issue | Description
--- | ---
[12](/issues/12) |
[23](/issues/23) | Some major update
[46](/issues/46) |

@param

@param <name> <description (optional)>

The @param tag is used to reference parameters for a given method. Use one for each parameter which should match the name of each parameter.

Example:

/**
 * ...
 * @param p_app_id APEX application ID
 * @param p_page_id APEX page ID
 * @param p_session_id
 * ...
 */

Template Reference:

{{#if params}}
### Parameters
Name | Description
--- | ---
{{#each params}}
{{name}} | {{{description}}}
{{/each}}
{{/if}} {{! params}}

Result:

### Parameters
Name | Description
--- | ---
p_app_id | APEX application ID
p_page_id | APEX page ID
p_session_id |

@private

The @private tag is used on private methods. You can chose if these methods should be displayed by the template. Reference it in the template by using the isPrivate attribute.

Each element in types and constants also contain the isPrivate boolean attribute. It is recommended to apply this tag to internal (package body) constants and types.

Example:

/**
 * ...
 * @private
 * ...
 */

Template Reference:

{{#each methods}}
{{#unless isPrivate}}

Items shown here will only be displayed if not private
{{/unless}}
{{/each}}

@return

@return Is used to describe the object returned by a function.

Example:

/**
 * ...
 * @param p_user_id
 * @return User first name
 * ...
 */

Template Reference: Note: since the @return option is very similar to an @param, it is recommended that it is included with parameters.

{{#ifCond params '||' return}}
### Parameters
Name | Description
--- | ---
{{#each params}}
{{name}} | {{{description}}}
{{/each}}
{{#if return}}
*return* | {{return}}
{{/if}} {{! return}}
{{/ifCond}} {{! params or return}}

Result:

### Parameters
Name | Description
--- | ---
p_user_id |
*return* | User first name

Package Level Comments

Packages may contain JavaDoc comments as well. The following is an example of package level documentation:

/**
 * Some package level comments
 * Another line
 * @author Martin D'Souza
 * @created 18-Jul-2017
 */
create or replace package body oos_util_apex
...

{{#if global}}
## Package Description
{{#if global.author}}Author: {{global.author}} {{/if}}
{{#if global.created}}Created: {{global.created}} {{/if}}
{{{global.description.full}}}
{{/if}}

@constants

Constants should be placed at the top of the package. There should only be one JavaDoc documentation area for constants. Constants are documented using the @constant tag and use the notation: @constant <constant name> <optional description>.

Example:

-- CONSTANTS
/**
 * @constant gc_color_red The css safe color for red
 * @constant gc_color_blue The css safe color for blue
 */

gc_color_red constant varchar2(10) := 'red';
gc_color_blue constant varchar2(10) := 'blue';

Template Reference: The @constant tag is referenced in the template as an array of objects. Each entry contains attributes: name, code, description, and isPrivate. The following example creates a header entry and a table of constants along with the code.

{{#each constants}}
{{#if @first}}
## Constants

Name | Code | Description
--- | --- | ---{{/if}}{{! first}}
{{name}} | `{{{code}}}` | {{description}}{{/each}}

Result:

## Constants

Name | Code | Description
--- | --- | ---
gc_color_red | `gc_color_red constant varchar2(10) := 'red';` | The css safe color for red
gc_color_blue | `gc_color_blue constant varchar2(10) := 'blue';` | The css safe color for blue

@types

Types are very similar to constants. They should be placed at the top of the package. There should only be one JavaDoc documentation area for constants. Types are documented using the @type tag and use the notation: @type <type name> <optional description>

Example:

-- TYPES
/**
 * @type rec_param Some custom record
 * @type tab_param Table of custom record
 */
type rec_param is record(
  name varchar2(255),
  val varchar2(4000));

type tab_param is table of rec_param index by binary_integer;

Template Reference: The @type tag is referenced in the template as an array of objects. Each entry contains attributes: name, code, description, isPrivate. The following example creates a header entry and a table of types along with the code. Note: types may contain multiline blocks of code. This does not work well with markdown tables. To get around this issue it is recommended to use the notation shown in the example.

{{#each types}}
{{#if @first}}
## Types

Name | Code | Description
--- | --- | ---{{/if}}{{! first}}
{{name}} | <pre>{{{lineBreakToBr code}}}</pre> | {{description}}{{/each}}

Result:

## Types

Name | Code | Description
--- | --- | ---
rec_param | <pre>type rec_param is record(<br />  name varchar2(255),<br />  val varchar2(4000));</pre> | Some custom record
tab_param | <pre>type tab_param is table of rec_param index by binary_integer;</pre> | Table of custom record