You can annotate *.pls and *.pkh files.

For PL/SQL packages, only the package specification should be annotated. Do not annotate the body.

Before annotating, make sure that no comments beginning with /*# are present. The "slash-star-pound" characters are used to set off repository annotations, and will result in either an error or undesirable behavior if used with normal comments.

To annotate, use a text editor (such as emacs or vi.) to edit the file. For each package, begin your annotations at the second line immediately after the CREATE OR REPLACE PACKAGE <package_name> AS line. (The first line after CREATE OR REPLACE PACKAGE <package_name> AS should be the /* $Header: appb_plsql.htm 120.16 2015/07/21 21:42:54 appldev noship $ */ line.)

Required Class-level Annotations

• must begin with description sentence(s)

• rep:scope

• rep:product

• rep:displayname

• rep:category

  Use BUSINESS_ENTITY at the class level only if all underlying methods have the same business entity. In those cases, you do not need to repeat the annotation at the method level.

• rep:businessevent (if an event is raised)

Optional Class-level Annotations

• link

• see

• rep:lifecycle

• rep:compatibility

• rep:ihelp

• rep:metalink

Required Method-level Annotations

• must begin with description sentence(s)

• param

  Use only when applicable and when other tags such as @see and @rep:metalink do not provide parameter explanations.

• return (if applicable)

• rep:displayname

• rep:paraminfo

• rep:businessevent (if an event is raised)

Optional Method-level Annotations

• link

• see

• rep:scope

• rep:lifecycle

• rep:compatibility

• rep:category

  Use BUSINESS_ENTITY at the method level only when a class methods have heterogeneous business entities.

• rep:ihelp

• rep:metalink

• rep:appscontext

• rep:primaryinstance

Template

You can use the following template when annotating PL/SQL files:

.
.
.
CREATE OR REPLACE PACKAGE <package name> AS
/* $Header: appb_plsql.htm 120.16 2015/07/21 21:42:54 appldev noship $ */
/*#
  * <Put your long package description here
  * it can span multiple lines>
  * @rep:scope <scope>
  * @rep:product <product or pseudoproduct short code>
  * @rep:lifecycle <lifecycle>
  * @rep:displayname <display name>
  * @rep:compatibility <compatibility code>
  * @rep:businessevent <Business event name>
  * @rep:category BUSINESS_ENTITY <entity name>
  */


 .
 .
 .


/**
 * <Put your long procedure description here
 * it can span multiple lines>
 * @param <param name 1> <param description 1>
 * @param <param name 2> <param description 2> 
 * @rep:scope <scope>
 * @rep:product <product or pseudoproduct short code>
 * @rep:lifecycle <lifecycle>
 * @rep:displayname <display name>
 * @rep:compatibility <compatibility code>
 * @rep:businessevent <Business event name>
 */
PROCEDURE <procedure name> ( . . .);

.
.
.

/**
 * <Put your long function description here
 * it can span multiple lines>
 * @param <param name 1> <param description 1>
 * @param <param name 2> <param description 2>
 * @return <return description>
 * @rep:scope <scope>
 * @rep:product <product or pseudoproduct short code>
 * @rep:lifecycle <lifecycle>
 * @rep:displayname <display name>
 * @rep:compatibility <compatibility code>
 * @rep:businessevent <Business event name>
 */
FUNCTION <function name> ( . . .);

.
.
.

END <package name>;
/

commit;
exit;

Example

For reference, here is an example of an annotated PL/SQL file:

set verify off
whenever sqlerror exit failure rollback;
whenever oserror exit failure rollback;


create or replace package WF_ENGINE as

/*#
 * This is the public interface for the Workflow engine.  It allows 
 * execution of various WF engine functions.
 * @rep:scope public
 * @rep:product WF
 * @rep:displayname Workflow Engine
 * @rep:lifecycle active
 * @rep:compatibility S
 * @rep:category BUSINESS_ENTITY WF_WORKFLOW_ENGINE
 */


g_nid number;          -- current notification id
g_text varchar2(2000); -- text information



--
-- AddItemAttr (PUBLIC)
--   Add a new unvalidated run-time item attribute.
-- IN:
--   itemtype - item type
--   itemkey - item key
--   aname - attribute name
--   text_value   - add text value to it if provided.
--   number_value - add number value to it if provided.
--   date_value   - add date value to it if provided.
-- NOTE:
--   The new attribute has no type associated.  Get/set usages of the
--   attribute must insure type consistency.
--
/*#
 * Adds Item Attribute
 * @param itemtype item type
 * @param itemkey item key
 * @param aname attribute name
 * @param text_value add text value to it if provided.
 * @param number_value add number value to it if provided.
 * @param date_value add date value to it if provided.
 * @rep:scope public
 * @rep:lifecycle active
 * @rep:displayname Add Item Attribute
 */
procedure AddItemAttr(itemtype in varchar2,
                      itemkey in varchar2,
                      aname in varchar2,
                      text_value   in varchar2 default null,
                      number_value in number   default null,
                      date_value   in date     default null);

--
-- AddItemAttrTextArray (PUBLIC)
--   Add an array of new unvalidated run-time item attributes of type text.
-- IN:
--   itemtype - item type
--   itemkey - item key
--   aname - Array of Names
--   avalue - Array of New values for attribute
-- NOTE:
--   The new attributes have no type associated.  Get/set usages of these
--   attributes must insure type consistency.
--


END WF_ENGINE;
/

commit;
exit;