29.2.1 JavaDoc

Table of Contents

29.2.1.1. JavaDoc Support

29.2.1.1 JavaDoc Support

The table below lists the JavaDoc tags that DVT recognizes. For more details see http://en.wikipedia.org/wiki/Javadoc.

@param	Valid for: functions, tasks Adds a parameter with the specified argument-name followed by the specified description to the "Arguments" section
@return	Valid for: functions Adds a "Returns" section with the description text. This text should describe the return type and permissible range of values
@see	Adds a "See Also" heading with a link or text entry that points to reference. A doc comment may contain any number of @see tags, all grouped under the same heading
@author	Adds an "Author" entry
@deprecated	Adds a comment indicating that this API should no longer be used (even though it may continue to work)
@version	Adds a "Version" subheading with the specified version-text
@since	Adds a "Since" heading with the specified since-text
{@link LINK_ADDRESS LINK_TEXT}	Inserts an in-line link with visible text label that points to the documentation for the specified package, class or member name of a referenced class. This tag is valid in all doc comments. For more details see below.
{@literal text}	Displays text without interpreting the text as HTML markup or nested javadoc tags. This enables you to use regular angle brackets (< and >) instead of the HTML entities (<and >) in doc comments, such as in parameter types (<Object>), inequalities (3 < 4), or arrows (<-)

JavaDoc Links

An in-line link in a comment can be created using this tag {@link LINK_ADDRESS LINK_TEXT}.There are two types of links:

Internal Links -> point to data inside Documentation. In this case LINK_ADDRESS must respect the following notation: Package_Name::Class_Name.Method_Name for an absolute path or

TYPE_NAME.INNER_TYPE_NAME or just TYPE_NAME for relative paths. In case of a relative path a link will be created to the best match for that type with regard to its scope inside the project. NOTE: Using relative paths could generate broken links if there are different data types with the same name inside the project!

External Links -> point to external web pages or files. For webpages LinkAddress must start with http:// and for files with file:// followed by the resource's address. For example: {@link https://www.dvteclipse.com} or {@link file://external-res.pdf}

For both types of links LINK_TEXT is optional and it can be used to show a user defined text instead of link's path.

JavaDoc Autocomplete and Comment Templates

To add JavaDoc like comments to code, in Code Editor type above the code declaration /** and then press Enter. Depending on the code type (a class declaration, a function, a task etc.) a comment will be added with the respective JavaDoc tags.

These comments are added based on some predefined comment templates that can be customized.

Go to Window > Preferences > DVT > SystemVerilog > Editor > Code Templates.You can select a javadoc template and modify it by adding/removing supported tags (using this naming convention: ${TagNameWithout@} ) or custom text.

You can also create new templates. A template will be applied only to a specified data type, for example: javadoc_class will be applied to classes. If you want to add a template for modules its name must respect the following rule: YourTemplateName_DataType (ex: MyModuleTemplate_module) and must be placed in JavaDoc Comment Context.

See the result in the image below: