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.

-- 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;
../../_images/vhdl_to_html.png

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

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.

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.

reStructuredText

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.

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.

Important

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

If the markup language preference is set to <doc-formatting-type>auto</doc-formatting-type>, 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.

bold text

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

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

**bold text**

*bold text*

italic text

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

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

*italic text*

~italic text~

  • Bullet one.

  • Bullet two.

  • Bullet three.

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

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

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

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

  1. Item 1.

  2. Item 2.

  3. Item 3.

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

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

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

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

description of item 1.

Item 2

description of item 2.

<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>

<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>

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

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

DVT Eclipse

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

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

For hyperlinks to other elements use:

[LABEL](#ELEMENT_NAME)
[LABEL][1]

[1]: #ELEMENT_NAME

In this case ELEMENT_NAME must respect the following notations:
(1) fully qualified names PACKAGE::CLASS.method
(2) TYPE_NAME.INNER_TYPE_NAME or just TYPE_NAME,
    solved relative to the enclosing scope

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

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 notations:
(1) fully qualified names PACKAGE::CLASS.method
(2) TYPE_NAME.INNER_TYPE_NAME or just TYPE_NAME,
    solved relative to the enclosing scope

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

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

For API Hyperlinks you can use the following syntax:

<LABEL: ELEMENT_NAME>

In this case ELEMENT_NAME must respect the following notations:
(1) fully qualified names PACKAGE::CLASS.method
(2) TYPE_NAME.INNER_TYPE_NAME or just TYPE_NAME,
    solved relative to the enclosing scope

Alternative text

![Alternative text](image.png)

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

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

// (see image.png)

Headings

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

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

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

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.

A simple code block example.

print("Hello, World!")

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

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

.. code-block:: python

    print("Hello, World!")

Not supported.

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

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

/**
 * <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>
 */

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

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

Not supported.