Skip to content
This repository has been archived by the owner on Aug 1, 2019. It is now read-only.

JavaDoc

Jump to bottom
Izzy edited this page Jan 29, 2018 · 1 revision

HyperSQL versions after v1.3 include support for Javadoc style comments. There is no plausibility check currently, so it's up to you to take care for correct spelling, syntax, and logic. Basically, you could define a procedure with an return value – sure, PL/SQL doesn't support this – but HyperSQL wouldn't complain. Just when writing the HTML code, it would ignore the @return value specified.

The same applies to the other keywords: if your inline documentation contains tags unsupported by HyperSQL, they will be silently ignored – so you can keep them in the hope they will be added (and file a ticket to request this), all other stuff will still be processed. A side effect of this is, possible typos are handled the same. To give you a chance to check for them, encountered unknowns are logged at the WARNING log level.

Description

_HyperSQL_s Javadoc parser is somehow limited – which forces you to stick to its rules. Together with those for the syntax highlighter, the good thing about it is it enforces a clean coding style ;) Please don't ask for it: These limitations will stay. It works this way, and I don't have the time for something more sophisticated.

So these are the rules, explained using an example:

  /** This is an example procedure. It does something special.
   *  I just cannot remember what.
   * @procedure special
   * @param in varchar2 command_me The special thing to do
   * @param in number many_times How often this should be done
   * @param inout varchar2 the_thing The thing to manipulate
   * @version $Id: javadoc.txt 6 2010-02-11 19:27:14Z izzy $
   */

Everything between the opening tag (/**) and the first line starting with @ will be treated as the description. For the overviews, a short description will be created from this - by cutting everything following the first "stop mark character" (dot, semi colon, line break). So in our example, the short desc would be: "This is an example procedure."

It is a good idea to start each new line with the star - this way, when browsing your code, it is easy to tell how far the comment goes. HyperSQL expects you doing so.

All information for a tag can be kept in one line – but (with versions post-3.7.5, i.e. starting with r165) they can also span multiple lines, which will make the JavaDoc block better human-readable in your source code.

Moreover, all Javadoc information for a given object MUST be kept in one block, i.e. enclosed between /** and */ - the parser will close at the */ mark. If you miss to specify the object type and name, everything else is probably lost (since HyperSQL would not know where it belongs to). However, there's a "fallback mode" available with which it may still work if your Javadoc block starts immediately before/after the object declaration itself, e.g.:

  CREATE OR REPLACE PACKAGE something AS
    /** This is some package */

This fallback can be controlled via the blind_offset setting in the [process] section of your Configuration. By default, it is switched off (blind_offset = 0; please see the Configuration page for details).

Most tags can be used multiple times for the same object: A function/procedure can of course have multiple parameters (but only one @return, one type and one name – if you define these tags more than once, the latter definition will overwrite the former), for example. Or you want to define multiple authors or multiple @todo items – it's possible.

Beside plain documentation, you may even embed test-cases here – for details, please see the UnitTest page.

Supported Tags

Object types

  • @form <name>: specifies an Oracle Form
  • @function <name>: specifies the name of a function
  • @mview <name>: specifies the name of a materialized view
  • @pkg <name>: specifies the name of a package
  • @procedure <name>: specifies the name of a procedure
  • @sequence <name>: specifies the name of a sequence
  • @synonym <name>: specifies the name of a synonym
  • @table <name>: specifies the name of a table
  • @trigger <name>: specifies the name of a trigger
  • @type <name>: specifies the name of a type
  • @view <name>: specifies the name of a view

<name> has to be a single word. Needless to say, you shouldn't use multiple object type declarations in one Javadoc block. It makes no sense – the object can just be of one type. HyperSQL would not care about – but the results are not predictable ;)

Another mark: I especially chose to use @pkg for packages, as @package is used in Javadoc style documentations for a different purpose. This way confusion should be avoided.

Object properties

  • @col <type> [<name> [<description>]]: describing a column (for (materialized) views and tables). Specifying multiple columns is of course possible. type is the SQL type of the column (e.g. NUMBER), and the only obligatory parameter for this tag.
  • @param [in|out|inout] <type> [<name> [<description>]]: describing a parameter to be passed to a function or procedure. Specify multiple parameters in the order they are passed to the function/procedure, so the documentation will honor this. The first parameter to this keyword is optional (defaults to in) – if used, it must be one of the three possibilities mentioned. Next comes the SQL type (one word only – if you need something special, like e.g. VARCHAR2(200), simply save the additions for the description. Two more optional arguments follow: The name of the argument (one word). And everything following the name, which makes the description.
  • @return <type> [<name> [<description>]]: describing a return value for a function. Arguments are explained above.
  • @throws <exception> [<description>]]: meant for procedures and functions which "raise" exceptions. It's called throws (instead of raises) since that's the original JavaDoc tags name.

Supplementary object information

  • @author <text>: information about the author of the documented object
  • @bug <text>: remark about bugs to be fixed here. Something like @todo with higher priority
  • @copyright <text>: copyright information
  • @deprecated <text>: for things just kept for compatibility reasons, which shall be removed soon. This tells the developers not to call this code in new development – and you can walk the "where used" list to eliminate old calls, so you finally can remove this one.
  • @example <text>: usage example
  • @ignore: ignore this object. If this tag is set, the corresponding function/procedure/… will not be listed with the created reference.
  • @ignorevalidation: do not validate Javadoc for this object. Useful e.g. for deprecated objects which are to be dropped soon and should not waste time on documentation
  • @info <text>: some additional information for developers using the code
  • @private: this function/procedure is not mentioned in the package specs, and hence only available inside this package ("internal helper")
  • @see <text>: point to other sources (most likely functions/procedures of the same package or at least the same product)
  • @since <text>: translates to Available since in the generated doc, so it's intended to put a version number and/or date here
  • @testcase <block>: defines a testcase (only useful for functions/procedures, whether stand-alone or in packages). See UnitTest for details.
  • @ticket <(id [text])|text>: more information can be found in a tracking system like Bugzilla. If the first param is numeric, and an URL was configured for a tracker instance, a hyperlink will be created from this. All following/other text will simply be displayed (after this).
  • @todo <text>: marks for the author on what should be done to the object in the future
  • @used <object>: declare resources depending on this object – e.g. packages from other Oracle schemata not recognized by HyperSQL since you don't have their code included
  • @uses <object>: declare required resources - e.g. packages from other Oracle schemata not recognized by HyperSQL since you don't have their code included
  • @verbatim: details that need to be pre-formatted (e.g. code samples)
  • @version <text>: some version info - any text may be passed. Useful for things like SVN keywords – so you can see what version of the object is described in the documentation you are reading later.
  • @webpage <url>: URL where to find more details
  • @wiki <page> [text]: more information can be found in a wiki page. If an URL was configured for a wiki instance, the first paramis expected to be the page name, and a corresponding link is created. All following/other text will be simpy displayed (after this).
Clone this wiki locally