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.

.. tab-set::

    .. tab-item:: VHDL

        .. code-block:: 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;

    .. tab-item:: HTML

        .. image:: ../../images/vhdl_to_html.png
            :align: center


Comments directives
-------------------

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

.. list-table::
    :widths: 30 70
    :header-rows: 1

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

Comments formatting
-------------------

Markdown (*recommended*)
    `Markdown <https://www.markdownguide.org/>`__ 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 <http://en.wikipedia.org/wiki/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 <https://www.sphinx-doc.org/en/master/>`_. 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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_.

Natural Docs (*deprecated*)
    `Natural Docs <http://www.naturaldocs.org/>`__ 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.

.. tab-set::

    .. tab-item:: Bold text

        **bold text**

    .. tab-item:: Markdown

        .. code-block:: html
              
            **bold text**
            __bold text__
            <b>bold text</b>
            <strong>bold text</strong>

    .. tab-item:: JavaDoc

        .. code-block:: java
              
            <b>bold text</b>
            <strong>bold text</strong>

    .. tab-item:: rST

        .. code-block:: rst
              
            **bold text**

    .. tab-item:: Natural Docs

        .. code-block::
            
            *bold text*

.. tab-set::

    .. tab-item:: Italic text

        *italic text*

    .. tab-item:: Markdown

        .. code-block:: html
              
            *italic text*
            _italic text_
            <i>italic text</i>
            <em>italic text</em>

    .. tab-item:: JavaDoc

        .. code-block:: java
              
            <i>italic text</i>
            <em>italic text</em>

    .. tab-item:: rST

        .. code-block:: rst
              
            *italic text*

    .. tab-item:: Natural Docs

        .. code-block::
            
            ~italic text~

.. tab-set::

    .. tab-item:: Bullet list

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

    .. tab-item:: Markdown

        .. code-block:: html
              
            - Bullet one.
            - Bullet two.
            - Bullet three.

    
    .. tab-item:: JavaDoc

        .. code-block:: java
              
            <ul>
              <li>Bullet one.</li>
              <li>Bullet two.</li>
              <li>Bullet three.</li>
            </ul>

    .. tab-item:: rST

        .. code-block:: rst
              
            - Bullet one.
            - Bullet two.
            - Bullet three.

    .. tab-item:: Natural Docs

        .. code-block::
            
            - Bullet one.
            - Bullet two.
            - Bullet three.


.. tab-set::

    .. tab-item:: Numbered list

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

    .. tab-item:: Markdown

        .. code-block:: html
              
            1. Item 1.
            2. Item 2.
            3. Item 3.

    .. tab-item:: JavaDoc

        .. code-block:: java
              
            <ol>
              <li>Item 1.</li>
              <li>Item 2.</li>
              <li>Item 3.</li>
            </ol>
    
    .. tab-item:: rST

        .. code-block:: rst
              
            #. Item 1.
            #. Item 2.
            #. Item 3.

    .. tab-item:: Natural Docs

        .. code-block::
            
            1. Item 1.
            2. Item 2.
            3. Item 3.


.. tab-set::

    .. tab-item:: Definition list

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

    .. tab-item:: Markdown

        .. code-block:: html
              
            <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>
    
    .. tab-item:: JavaDoc

        .. code-block:: java
              
            <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>

    .. tab-item:: rST

        .. code-block:: rst
              
            Item 1
                description of item 1.
            Item 2
                description of item 2.

    .. tab-item:: Natural Docs

        .. code-block::
            
          Item 1 - description of item 1
          Item 2 - description of item 2


.. tab-set::

    .. tab-item:: Hyperlinks

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

    .. tab-item:: Markdown

        .. code-block:: rst
            :emphasize-lines: 6,13-16

            [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
    
            
    .. tab-item:: JavaDoc

        .. code-block:: rst
            :emphasize-lines: 3,8-11

            @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

    .. tab-item:: rST

        .. code-block:: rst

            `DVT Eclipse <https://eda.amiq.com>`__
              
    .. tab-item:: Natural Docs

        .. code-block::
            :emphasize-lines: 3,7-10
            
            <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

.. |top-icon| image:: ../../images/virtual_interface.png
    :class: inline
    :alt: Alternative text

.. tab-set::

    .. tab-item:: Images

        |top-icon|
              
    .. tab-item:: Markdown

        .. code-block:: html

            ![Alternative text](image.png)
        
        .. note::

            Relative paths are first solved as relative to the current file, then as relative to the project root.
    
            
    .. tab-item:: JavaDoc

        .. code-block:: java

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

    .. tab-item:: rST

        .. code-block:: rst

            .. figure:: path/image.png
                :alt: Alternative text
              
    .. tab-item:: Natural Docs

        .. code-block::

            // (see image.png)

.. tab-set::

    .. tab-item:: Headings

        **Headings**
              
    .. tab-item:: Markdown

        .. code-block:: html

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

    .. tab-item:: JavaDoc

        .. code-block:: java

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

    .. tab-item:: rST

        .. code-block:: rst

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

    .. tab-item:: Natural Docs

        .. code-block::

            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.
            
.. tab-set::

    .. tab-item:: Code Block

        A simple code block example.

        .. code-block:: rst
            
            print("Hello, World!")

    .. tab-item:: Markdown

        .. code-block:: markdown

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

    .. tab-item:: JavaDoc

        .. code-block:: java

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

    .. tab-item:: rST

        .. code-block:: rst

            .. code-block:: python

                print("Hello, World!")

    .. tab-item:: Natural Docs

        Not supported.

.. tab-set::

    .. tab-item:: 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  |
        +------------+-------------+

    .. tab-item:: Markdown

        .. code-block:: markdown
              
            | Header 1   | Header 2   |
            |------------|------------|
            | Row 1 Col1 | Row 1 Col2 |
            | Row 2 Col1 | Row 2 Col2 |

    .. tab-item:: JavaDoc

        .. code-block:: java
              
            /**
             * <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>
             */

    .. tab-item:: rST

        .. code-block:: rst
              
            .. list-table:: Example Table
               :header-rows: 1

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

    .. tab-item:: Natural Docs

        Not supported.

.. tab-set::

    .. tab-item:: Admonitions

        A simple admonition example.

        .. admonition:: Note title
            
            Note content

    .. tab-item:: Markdown

        .. code-block:: markdown

            !!! note Note title
            
            You can also use info, question, quote, abstract, attention, bug, caution, danger, error, example or hint.
             
            !!!

    .. tab-item:: JavaDoc

        Not supported.

    .. tab-item:: rST

        .. code-block:: rst

            .. admonition:: Note title

                Note content

    .. tab-item:: Natural Docs

        Not supported.




