Configurations using XML preferences

Specador provides a comprehensive set of configurable preferences, enabling users to enhance the generated documentation.

In order to generate diagrams, filter third-party API or use comment formatters an XML file is provided:

$ $DVT_HOME/bin/specador.sh ... -preferences specador_preferences.xml

Use -gen_preferences_xml to generate a file containing all the preferences with their default values:

$ $DVT_HOME/bin/specador.sh -gen_preferences_xml

Elements description can be tuned and filtered using the following preferences:

<!-- Syntax for comments formatting: reStructuredText, markdown, javadoc, naturaldocs, auto or noformat. -->
<doc-formatting-type>reStructuredText</doc-formatting-type>
<!-- Inline or above comments containing one of the keywords from this list (comma separated list) will not be included. Change the strategy attribute to 'line' to skip only the lines that contain one of the keywords. -->
<filter-comments strategy="line">Copyright,Revision,License</filter-comments>
<!-- Collect comments content after the specified tag. -->
<filter-comments-start-tag>Description:</filter-comments-start-tag>
<!-- Collect comments content until the specified tag. -->
<filter-comments-end-tag>License:</filter-comment-end-tag>

You can select which libraries and which kind of API to include in the documentation using the following preferences:

• SystemVerilog Specific

<!-- Export variables declared inside modules. -->
<export-vlog-modules-variables>false</export-vlog-modules-variables>
<!-- Generate macros documentation. -->
<export-vlog-macros>true</export-vlog-macros>
<!-- Generate ifndef guards documentation. Default: false. -->
<export-vlog-ifndef-guards>false</export-vlog-ifndef-guards>
<!-- Generate control defines documentation. Default: true. -->
<export-vlog-control-defines>true</export-vlog-control-defines>
<!-- Generate assertions documentation. -->
<export-vlog-assertions>true</export-vlog-assertions>
<!-- Generate covergroups documentation. -->
<export-vlog-covergroups>true</export-vlog-covergroups>
<!-- Generate libraries documentation. You can select the specific packages you want to document using export-vlog-library tag. For all libraries set export-vlog-libraries to true.-->
<export-vlog-libraries>
    <export-vlog-library name="libA">true</export-vlog-library>
    <export-vlog-library name="libB">
        <export-vlog-modules>true</export-vlog-modules>
        <export-vlog-interfaces>true</export-vlog-interfaces>
        <export-vlog-packages>true</export-vlog-packages>
    </export-vlog-library>
    <export-vlog-library name="work">
        <export-vlog-packages>
            <export-vlog-package>pkgA</export-vlog-package>
        </export-vlog-packages>
    </export-vlog-library>
</export-vlog-libraries>

• VHDL Specific

<!-- Generate libraries documentation. You can select the specific libraries you want to document using export-vhdl-library tag. For all libraries set export-vhdl-libraries to true.-->
<export-vhdl-libraries>
    <export-vhdl-library name="libA">true</export-vhdl-library>
    <export-vhdl-library name="libB">
        <export-vhdl-entities>true</export-vhdl-entities>
        <export-vhdl-packages>true</export-vhdl-packages>
    </export-vhdl-library>
    <export-vhdl-library name="work">
        <export-vhdl-packages>
            <export-vhdl-package>pkgA</export-vhdl-package>
        </export-vhdl-packages>
    </export-vhdl-library>
</export-vhdl-libraries>

• ELanguage Specific

<!-- Generate macro documentation. -->
<export-e-macro>true</export-e-macro>
<!-- Generate covergroups documentation. -->
<export-e-covergroups>true</export-e-covergroups>
<!-- Generate checks documentation. -->
<export-e-checks>true</export-e-checks>
<!-- Generate tests documentation. -->
<export-e-tests>true</export-e-tests>
<!-- Generate packages documentation. You can select the specific packages you want to document using export-e-package tag. For all packages set export-e-packages to true.-->
<export-e-packages>
    <export-e-package>pkgA</export-e-package>
    <export-e-package>pkgB</export-e-package>
</export-e-packages>

The generated documentation can be further filtered using a combination of the following preferences:

<!-- Generate documentation only for public API. -->
<public-only>true</public-only>
<!-- Include design parameters in the instances and submodules hierarchies. -->
<include-design-parameters>true</include-design-parameters>
<!-- API matching the below filters with not be included in the generated documentation. Default: none. You can specify a comma-separated list of name patterns. Patterns may contain: * = any string, ? = any character. -->
<filter-string>m_*,M_*,UVM_*_SVH,UVM_*_SV</filter-string>
<!-- You can specify one or more file or directory paths. -->
<filter-path>src/pkgA</filter-path>
<filter-path>src/pkgB</filter-path>
<!-- Only API defined under the specified paths will be included. -->
<include-path>src</include-path>

Specador will export specific diagrams depending on the selected preferences:

<!-- Generate UML inheritance diagram for each class. -->
<export-uml-inheritance-diagram>false</export-uml-inheritance-diagram>
<!-- Generate UVM Component diagrams for each test. -->
<export-uvm-test-diagram>true</export-uvm-test-diagram>
<!-- Generate UML collaboration diagram for each class, struct, or unit. -->
<export-uml-collaboration-diagram>false</export-uml-collaboration-diagram>
<!-- Use orthogonal edge routing for class diagrams. -->
<orthogonal-class-diagrams>false</orthogonal-class-diagrams>
<!-- Generate design block diagram for each module, entity. -->
<export-design-block-diagram>false</export-design-block-diagram>
<!-- Generate design flow diagram for each module, entity. -->
<export-design-flow-diagram>false</export-design-flow-diagram>
<!-- Generate design schematic diagram for each module, entity. -->
<export-design-schematic-diagram>false</export-design-schematic-diagram>
<!-- Generate design schematic diagram without logic gates for each module/architecture. -->
<export-design-subinstances-diagram>false</export-design-subinstances-diagram>
<!-- Generate finite-state machine diagrams for all state variables found in the module, entity. -->
<export-fsm-diagrams>false</export-fsm-diagrams>
<!-- Direction for the FSM Diagrams: Up, Down, Left or Right -->
<fsm-diagram-direction>Down</fsm-diagram-direction>
<!-- Placement strategy for FSM Diagrams: Brandes-Koepf or Network Simplex -->
<fsm-placement-strategy>Brandes-Koepf</fsm-placement-strategy>
<!-- Enforce the in/out connections between states: None, All States or All States Except Initial -->
<fsm-enforce-edge-port-side>All States Except Initial</fsm-enforce-edge-port-side>
<!-- Position for initial state in FSM Diagram: Free, First or Last -->
<fsm-initial-state-position>First</fsm-initial-state-position>
<!-- Show default state in FSM Diagrams -->
<fsm-show-default-state>true</fsm-show-default-state>
<!-- Show loopback edges in FSM Diagrams -->
<fsm-show-loopback-edges>false</fsm-show-loopback-edges>
<!-- Generate bitfield diagram for each UVM register. -->
<export-bitfield-diagram>false</export-bitfield-diagram>

Note

A list of all the supported preference tags can be generated using the specador.sh -gen_preferences_xml