Add External Markdown Descriptions

Specador provides the ability to add descriptions for code elements from external Markdown files, allowing you to document your code without modifying the source files directly.

This feature is particularly useful when:

  • Working with legacy projects where modifying source code is not desirable

  • Keeping source files clean and focused on implementation

  • Managing documentation separately from code

Overview

The external Markdown descriptions feature allows you to:

  1. Generate a template Markdown file containing all documentable elements from a particular file

  2. Add or edit descriptions for any element in the Markdown file using standard Markdown syntax

  3. Automatically include these descriptions in the generated documentation

When generating documentation, Specador will prioritize external Markdown descriptions over inline comments for elements that have both.

Generating the External Markdown Template

You can generate an external Markdown template file that lists all documentable elements from a source code file.

Using Command Line

Use the -generate_markdown_file argument to generate one or multiple template files:

$ $DVT_HOME/bin/specador.sh -lang vlog -cmd /path/to/compile.build -generate_markdown_file /path/to/module.sv

This will create a Markdown file at the specified path containing entries for all documentable elements (modules, classes, functions, ports, etc.) found after compilation.

Using DVT IDE for Eclipse

To generate the external Markdown template from DVT IDE for Eclipse:

  1. Right-click on your SysemVerilog/VHDL/eLanguage file in the Project Explorer

  2. Select Specador > Generate Markdown File from the context menu

  3. The generated file will be automatically opened in the editor

Using DVT IDE for VS Code

To generate the external Markdown template from DVT IDE for VS Code:

  1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)

  2. Type and select Specador: Generate Markdown File

  3. The generated file will be automatically opened in the editor

External Markdown File Structure

To add descriptions for elements, simply write Markdown-formatted text below the corresponding heading:

Adding descriptions in external Markdown file
# module uart_transmitter

This module implements a UART transmitter that converts parallel data
to serial format according to the UART protocol.

**Features:**
- Configurable baud rate
- Support for 7, 8, or 9 data bits
- Optional parity (even, odd, or none)
- 1 or 2 stop bits

## Ports
### tx_data

The 8-bit parallel data to be transmitted. Data is sampled on the
rising edge of `clk` when `tx_valid` is asserted.

### tx_valid

Active-high signal indicating that `tx_data` contains valid data
ready for transmission.

You can use any standard Markdown formatting including:

  • Bold and italic text

  • Bullet lists and numbered lists

  • Code blocks and inline code

  • Tables

  • Links and images

For supported Markdown syntax, refer to the Comments formatting section.