[[TOC(Documentation,Installation,Configuration,Usage,Usage/*,JavaDoc,UnitTest,SyntaxHighlighting,Localization, depth=3)]] == Support for Javadoc style comments == ''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.: {{{ #!sql 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 [wiki:Configuration#Process Configuration]. By default, it is switched off (blind_offset = 0; please see the [wiki:Configuration#Process 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 `: specifies an Oracle Form * `@function `: specifies the name of a function * `@mview `: specifies the name of a materialized view * `@pkg `: specifies the name of a package * `@procedure `: specifies the name of a procedure * `@sequence `: specifies the name of a sequence * `@synonym `: specifies the name of a synonym * `@table `: specifies the name of a table * `@trigger `: specifies the name of a trigger * `@type `: specifies the name of a type * `@view `: specifies the name of a view `` 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 cunfusion should be avoided. ==== Object properties ==== * `@col [ []]`: 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] [ []]`: 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 [ []]`: describing a return value for a function. Arguments are explained above. * `@throws []]`: 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 `: information about the author of the documented object * `@bug `: remark about bugs to be fixed here. Something like `@todo` with higher priority * `@copyright `: copyright information * `@deprecated `: 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 `: usage example * `@ignore`: ignore this object. If this tag is set, the corresponding function/procedure/... will not be listed with the created reference. * `@info `: 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 `: point to other sources (most likely functions/procedures of the same package or at least the same product) * `@since `: translates to ''Available since'' in the generated doc, so it's intended to put a version number and/or date here * `@testcase `: 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 [http://en.wikipedia.org/wiki/Bug_tracking_system tracking system] like [http://en.wikipedia.org/wiki/Bugzilla Bugzilla]. If the first param is numeric, and an URL was [wiki:Configuration#General configured] for a tracker instance, a hyperlink will be created from this. All following/other text will simply be displayed (after this). * `@todo `: marks for the author on what should be done to the object in the future * `@used `: 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 `: declare required resources - e.g. packages from other Oracle schemata not recognized by ''HyperSQL'' since you don't have their code included * `@version `: 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 where to find more details * `@wiki [text]`: more information can be found in a wiki page. If an URL was [wiki:Configuration#General configured] for a wiki instance, the first param is expected to be the page name, and a corresponding link is created. All following/other text will be simpy displayed (after this).