Rev. 19.1.21, 21 June 2019

24.2.1 JavaDoc

Table of Contents JavaDoc Support 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: