Where can I find a syntax reference for Oracle SQL Developer's "Generate DB Doc" function?

Question

Oracle SQL Developer (I'm using v3.2) has a feature called "DB Doc", which generates documentation for database objects. I mostly want to use it to generate documentation for my stored procedures, functions, packages and types. However, I can't find any documentation for it, describing what syntax I should use.

I have worked out that I should use a /* ... */ comment on the line(s) immediately above my procedure/whatever, and (by borrowing from JavaDoc) I have successfully used @param and @returns statements, but I'm not sure what else I can use. For example, are there fields for author, version, data modified, etc.?

I've done numerous searches of this site, Google, and Oracle's documentation, to no avail!

• Arun Kumar: Here is some information from Oracle Guru Jeff Smith. thatjeffsmith.com/archive/2012/03/…

Answer 1

_{Community wiki answer initially based on comments left by thatjeffsmith:}

This is an exhaustive list of what it supports:

(reproduced from http://pldoc.sourceforge.net/maven-site/samples/sample1.sql)

CREATE OR REPLACE
PACKAGE CUSTOMER_DATA
IS
/** 
* Project: Test Project (<a href="http://pldoc.sourceforge.net">PLDoc</a>)<br/>
* Description: Customer Data Management<br/>
* DB impact: YES<br/>
* Commit inside: NO<br/>
* Rollback inside: NO<br/>
* @headcom
*/
/**
* Record of customer data.
*
* @param id customer ID
* @param name customer name
* @param regno registration number or SSN
* @param language preferred language
*/
TYPE customer_type IS RECORD (
 id VARCHAR2(20),
 name VARCHAR2(100),
 regno VARCHAR2(50),
 language VARCHAR2(10)
);
/** Table of customer records. */
TYPE customer_table IS TABLE OF customer_type INDEX BY BINARY_INTEGER;
/**
* Gets customer by ID.
*
* @param p_id customer ID
* @param r record of customer data
* @throws no_data_found if no such customer exists
*/
PROCEDURE get_customer (
 p_id VARCHAR2,
 customer_rec OUT customer_type);
/**
* Searches customer by criteria.
*
* @param p_criteria record with assigned search criteria
* @param r_records table of found customers <b>(may be empty!)</b>
*/
PROCEDURE get_by_criteria (
 p_criteria customer_type,
 r_records OUT customer_table);
/**
* Creates a customer record.
*
* @param customer_rec record of customer data
*/
PROCEDURE create_customer (
 customer_rec customer_type);
/**
* Changes customer data.
*
* @param customer_rec record of updated customer data
*/
PROCEDURE update_customer (
 customer_rec customer_type);
END;
/

We support everything in PLDOC - we just have a GUI vs a CLI for it. There are three code samples there, you should be able to do anything listed in those samples.

Answer 2

I would recommend to use PLDOC for PLSQL Documentation generation. It's similar to JavaDoc (slightly limited functionality, but has basics like @return, @throw, @param and etc.).

• Allan Lewis: I agree, but this isn't really an answer to my question - @thatjeffsmith did that in a comment above.