Comments Formatting

DVT automatically selects between Markdown, Javadoc and Natural Docs for each comment based on the syntax. If no syntax is detected, the comment will be rendered as it is.

Markdown (recommended)

Markdown is one of the world’s most popular markup languages that can be used to add formatting elements to plaintext text documents.

Markdown uses symbols like asterisks and dashes to create formatting like headings and bold text. This makes it quicker to write than complex HTML code.

It prioritizes readability by utilizing plain text and clear symbols to ensure the code remains easy to understand.

Comments written in Markdown will be formatted based on the following syntax:

Bold Font

// **This word** and __this word__ should be bolded
function bit my_function(bit argument);
endfunction

Italic Font

// *This word* and _this word_ should be in italic font
// ***This word*** should be italic and bolded
function bit my_function(bit argument);
endfunction

Bullet List

// Below is a list
// + This is the first element
// + This is the second element
// This is the continuation of
// the second element
function bit my_function(bit argument);
endfunction

Numbered List

// Below is a list
//  1. First Item
//  2. Second Item
//  3. Third Item
function bit my_function(bit argument);
endfunction

Heading

// # This is a level 1 heading
// ## This is a level 2 heading
// ###### This is a level 6 heading
function bit my_function(bit argument);
endfunction

Image

// Below you can see a section of a diagram
//
// ![Alternative text](diagram_section.png)
function bit my_function(bit argument);
endfunction

Note

The path can be either absolute, relative to the current file or relative to additional image locations. To specify additional image locations use dvt_documentation_resource_locations_add directive.

Link

// [DVT Eclipse](https://eda.amiq.com)
// [DVT Eclipse][1]
//
// [1]: https://eda.amiq.com
//
// [LABEL](#ELEMENT_NAME)
// [LABEL][2]
//
// [2]: #ELEMENT_NAME
function bit my_function(bit argument);
endfunction

Note

If you Ctrl+right click on a link that contains an object name, it should jump to its declaration.

ELEMENT_NAME must respect the following notations:

fully qualified names PACKAGE::CLASS.method
TYPE_NAME.INNER_TYPE_NAME or just TYPE_NAME, solved relative to the enclosing scope

Quote

// > This is a quote
function bit my_function(bit argument);
endfunction

Start Code

// Below is a code section
//
//     int a;
//     if ( a > 4 )
//        return 4;
//     return a;
function bit my_function(bit argument);
endfunction

Table

// | Header 1   | Header 2   |
// |------------|------------|
// | Row 1 Col1 | Row 1 Col2 |
// | Row 2 Col1 | Row 2 Col2 |
function bit my_function(bit argument);
endfunction

Javadoc

Javadoc syntax relies on specific tags to guide how information is displayed in the generated documentation.

These tags can offer insights into your code’s functionality, can facilitate documentation organization, and can enable linking to other elements.

Comments written in Javadoc will be formatted based on the following tags:

@author
@link
Note

As links you can have: an element name, a file, a valid web URL. If you Ctrl+right click on a link that contains an object name, it should jump to its declaration.

The element name must respect the following notations:
- fully qualified names PACKAGE::CLASS.method
- TYPE_NAME.INNER_TYPE_NAME or just TYPE_NAME, solved relative to the enclosing scope
@param
@return
@see

Note

Works similar to @link, but it will be placed in a separate section at the bottom of the comment, named “See also”.
@since
@version

Natural Docs (deprecated)

Important

Natural Docs format is deprecated and will no longer receive updates, but support for existing functionality will continue.

You must include at least one Natural Docs-specific syntax element (Topics, Hyperlinks, Images or Definition List) to prevent conflicts with Markdown syntax, which takes precedence.

Natural Docs is an open source documentation generator for multiple programming languages. You document your code in a natural syntax that reads like plain English.

Comments written in Natural Docs will be formatted based on the following syntax:

Bold Font

// *This word* should be bolded
function bit my_function(bit argument);
endfunction

Bullet List

// Below is a list
// + This is the first element
// + This is the second element
// This is the continuation of
// the second element
function bit my_function(bit argument);
endfunction

Definition List

// Below is a definition list
// First Item - This is the definition
// of the first Item
// Second Item - This is the deinition
// of the second item
function bit my_function(bit argument);
endfunction

Heading

// Before
//
// Title of the heading:
// Content of the heading
//
// After
function bit my_function(bit argument);
endfunction

Image

// Below you can see a section of a diagram
//
// (see diagram_section.png)
function bit my_function(bit argument);
endfunction

Note

The path can be either absolute, relative to the current file or relative to additional image locations. To specify additional image locations use dvt_documentation_resource_locations_add directive.

Italic Font

// ~This word~ should be in italic font
function bit my_function(bit argument);
endfunction

Link

// Check this function out <my_other_function>
function bit my_function(bit argument);
endfunction

Note

As links you can have: an element name, a file, a valid web URL. If you Ctrl+right click on a link that contains an object name, it should jump to its declaration.

The element name must respect the following notations:

fully qualified names PACKAGE::CLASS.method
TYPE_NAME.INNER_TYPE_NAME or just TYPE_NAME, solved relative to the enclosing scope

Start Code

// Below is a code section
// (start code)
//   int a;
//   if ( a > 4 )
//      return 4;
//   return a;
// (end)
function bit my_function(bit argument);
endfunction

Topic Line

// Below you can see a topic line
//
// Function: my_first_function
function bit my_function(bit argument);
endfunction

Underline Font

// _This word_ should be underlined
function bit my_function(bit argument);
endfunction