Comments

Specador automatically collects comments during compilation and includes them in the generated documentation.

By default, comments written above or inline a declared element, such as ports, modules or classes will be collected.

VHDL

-- Instantiates chip-specific :abbr:`DDR (Double Data Rate)` input and output
-- registers.
--
-- Both data ``DataOut_high/low`` as well as ``OutputEnable`` are sampled with
-- the ``rising_edge(Clock)`` from the on-chip logic. ``DataOut_high`` is brought
-- out with this rising edge. ``DataOut_low`` is brought out with the falling
-- edge.
--
-- ``OutputEnable`` (Tri-State) is high-active. It is automatically inverted if
-- necessary. Output is disabled after power-up.
--
-- Both data ``DataIn_high/low`` are synchronously outputted to the on-chip logic
-- with the rising edge of ``Clock``. ``DataIn_high`` is the value at the ``Pad``
-- sampled with the same rising edge. ``DataIn_low`` is the value sampled with
-- the falling edge directly before this rising edge. Thus sampling starts with
-- the falling edge of the clock as depicted in the following waveform.
--
-- @WAVEDROM_START
--
--    { signal: [
--      ['DataOut',
--        {name: 'ClockOut',        wave: 'LH.L.H.L.H.L.H.L.H.L.H.'},
--        {name: 'ClockOutEnable',  wave: '0..1...................'},
--        {name: 'OutputEnable',    wave: '0.......1.......0......'},
--        {name: 'DataOut_low',     wave: 'x.......2...4...x......', data: ['4',      '6'],      node: '........k...m...o..'},
--        {name: 'DataOut_high',    wave: 'x.......3...5...x......', data: ['5',      '7'],      node: '........l...n...p..'}
--        ],
--        {},
--        {name: 'Pad',             wave: 'x2.3.4.5.z...2.3.4.5.z.', data: ['0', '1', '2', '3', '4', '5', '6', '7'], node: '.a.b.c.d.....e.f.g.h.'},
--        {},
--      ['DataIn',
--        {name: 'ClockIn',         wave: 'L.H.L.H.L.H.L.H.L.H.L.H'},
--        {name: 'ClockInEnable',   wave: '01.......0.............'},
--        {name: 'DataIn_low',      wave: 'x.....2...4...z...2...4', data: ['0',      '2',      '4'],      node: '......u...w.......y..'},
--        {name: 'DataIn_high',     wave: 'x.....3...5...z...3...5', data: ['1',      '3',      '5'],      node: '......v...x.......z..'}
--      ]
--      ],
--      edge: ['a~>u', 'b~>v', 'c~>w', 'd~>x', 'k~>e', 'l~>f', 'm~>g', 'n~>h', 'e~>y', 'f~>z'],
--      foot: {
--        text: ['tspan',
--          ['tspan', {'font-weight': 'bold'}, 'PoC.io.ddrio.inout'],
--          ' -- DDR Data Input/Output sampled from pad.'
--        ]
--      }
--    }
--
-- @WAVEDROM_END
--
-- ``Pad`` must be connected to a PAD because FPGAs only have these registers in
-- IOBs.

entity ddrio_inout is
    generic (
        BITS                        : positive
    );
    port (
        ClockOut            : in            std_logic;
        ClockOutEnable      : in            std_logic;
        OutputEnable        : in            std_logic;
        DataOut_high        : in            std_logic_vector(BITS - 1 downto 0);
        DataOut_low         : in            std_logic_vector(BITS - 1 downto 0);

        ClockIn         : in                std_logic;
        ClockInEnable       : in            std_logic;
        DataIn_high         : out           std_logic_vector(BITS - 1 downto 0);
        DataIn_low          : out           std_logic_vector(BITS - 1 downto 0);

        Pad             : inout     std_logic_vector(BITS - 1 downto 0)
    );
end entity;

HTML

Comments directives

There are a couple of compile directives the user can pass through using -cmd, in order to configure the collection of comments:

Directive	Note
+dvt_extract_comment_above+<true/false>	Extract comments above elements. Default: true.
+dvt_extract_comment_above_max_empty_lines+<number_of_lines>	Extract comment if located at no more than specified number of empty lines above element declaration. Default: 1.
+dvt_extract_comment_bcd+<true/false>	Extract /** begin comment delimiter comments. Default: true.
+dvt_extract_comment_header+<true/false>	Extract file header comments and associate them with the first element in file (module, entity etc.). Default: false.
+dvt_extract_comment_inline+<true/false>	Extract comments inline with elements. Default: true.
+dvt_extract_comment_ml+<true/false>	Extract /* multi line comments. Default: true.
+dvt_extract_comment_sl+<true/false>	Extract // single line comments. Default: true.

Comments formatting

reStructuredText (recommended)

reStructuredText(rST) is the default plaintext markup language used by Sphinx. rST syntax was designed to be a simple, unobtrusive markup language.

The format uses simple symbols like underlining to denote structure, making it readable without needing to learn complex codes. It emphasizes clear organization of your descriptions through elements like headings, lists, and quotes.

For a complete breakdown of the reStructuredText syntax Specador recognizes, please refer to the reStructuredText documentation.

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.

Natural Docs (deprecated)

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.

JavaDoc (deprecated)

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.

Bold text

bold text

rST

**bold text**

Markdown

**bold text**
__bold text__
<b>bold text</b>
<strong>bold text</strong>

Natural Docs

*bold text*

JavaDoc

<b>bold text</b>
<strong>bold text</strong>

Italic text

italic text

rST

*italic text*

Markdown

*italic text*
_italic text_
<i>italic text</i>
<em>italic text</em>

Natural Docs

~italic text~

JavaDoc

<i>italic text</i>
<em>italic text</em>

Bullet list

• Bullet one.

• Bullet two.

• Bullet three.

rST

- Bullet one.
- Bullet two.
- Bullet three.

Markdown

- Bullet one.
- Bullet two.
- Bullet three.

Natural Docs

- Bullet one.
- Bullet two.
- Bullet three.

JavaDoc

<ul>
  <li>Bullet one.</li>
  <li>Bullet two.</li>
  <li>Bullet three.</li>
</ul>

Numbered list

1. Item 1.

2. Item 2.

3. Item 3.

rST

#. Item 1.
#. Item 2.
#. Item 3.

Markdown

- Bullet one.
- Bullet two.
- Bullet three.

Natural Docs

1. Item 1.
2. Item 2.
3. Item 3.

JavaDoc

<ol>
  <li>Item 1.</li>
  <li>Item 2.</li>
  <li>Item 3.</li>
</ol>

Definition list

Item 1

description of item 1.

Item 2

description of item 2.

rST

Item 1
    description of item 1.
Item 2
    description of item 2.

Markdown

Item 1:     description of item 1.
Item 2:     description of item 2.

Natural Docs

Item 1 - description of item 1
Item 2 - description of item 2

JavaDoc

<dl>
  <dt><strong>Item 1</strong></dt>
  <dd>description of item 1.</dd>
  <dt><strong>Item 2</strong></dt>
  <dd>description of item 2</dd>
</dl>

Hyperlinks

DVT Eclipse

rST

`DVT Eclipse <https://eda.amiq.com>`__

Markdown

[DVT Eclipse](https://eda.amiq.com)

[DVT Eclipse][1]

[1]: https://eda.amiq.com

Natural Docs

<DVT Eclipse: https://eda.amiq.com>

Note

For API Hyperlinks you can use the following syntax:

<LABEL: ELEMENT_NAME>

In this case ELEMENT_NAME 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.

JavaDoc

@see <a href="https://eda.amiq.com">DVT Eclipse</a>

Note

For API Hyperlinks you can use the following syntax:

@see ELEMENT_NAME

{@link ELEMENT_NAME LABEL}

In this case ELEMENT_NAME 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.

Images

rST

.. figure:: path/image.png
    :alt: Alternative text

Markdown

![Alternative text](image.png)

Natural Docs

// (see image.png)

JavaDoc

/**
  * <img src="./doc-files/image.png" alt="Alternative text" />
  */

Headings

Headings

rST

Different heading levels in rST are indicated by underlining with
various characters (=, -, ~, etc.), corresponding to their level.

Markdown

Uses hash symbols (#) for different heading levels. One # for heading
level 1, two for heading level 2, and so on.

Natural Docs

To make a heading you must skip a line, write the heading in title-case,
and end it with a colon.

Parameters:

    This is where you would describe the parameters.

Returns:

    This is where you would describe the return value.

See Also:

    This is where you would include relevant links.

JavaDoc

HTML tags like <h1>, <h2>, and <h3> are used to denote different heading levels.

Code Block

A simple code block example.

print("Hello, World!")

rST

.. code-block:: python

    print("Hello, World!")

Markdown

```python
print("Hello, World!")
```

Natural Docs

Not supported.

JavaDoc

/**
 * <pre>
 * print("Hello, World!");
 * </pre>
 */

Tables

A simple table example with two columns and three rows:

Header 1	Header 2
Row 1 Col1	Row 1 Col2
Row 2 Col1	Row 2 Col2

rST

.. list-table:: Example Table
   :header-rows: 1

   * - Header 1
     - Header 2
   * - Row 1 Col1
     - Row 1 Col2
   * - Row 2 Col1
     - Row 2 Col2

Markdown

| Header 1   | Header 2   |
|------------|------------|
| Row 1 Col1 | Row 1 Col2 |
| Row 2 Col1 | Row 2 Col2 |

Natural Docs

Not supported.

JavaDoc

/**
 * <table>
 *   <tr>
 *     <th>Header 1</th>
 *     <th>Header 2</th>
 *   </tr>
 *   <tr>
 *     <td>Row 1 Col1</td>
 *     <td>Row 1 Col2</td>
 *   </tr>
 *   <tr>
 *     <td>Row 2 Col1</td>
 *     <td>Row 2 Col2</td>
 *   </tr>
 * </table>
 */