Overview

This article covers systematic comment conventions for Verilog code and the TerosHDL VSCode extension for automated documentation generation.

Comment Syntax Implementation

Verilog supports the same comment syntax as C/C++:

Single-line comments: // comment text Multi-line comments: /* comment block */

Two-Layer Comment Architecture

To accommodate Verilog's description characteristics and maintain code organization, a two-layer comment system proves effective:

Structure Layer

Structure comments use a series of equal signs to demarcate major code sections:

//======================================================== // Function and mathematical operations //========================================================

This layer enforces a consistent code organization sequence:

Parameter declarations Local parameter definitions Register and wire declarations Combinational and sequential logic Module instantiations Task and function definitions Debug logic (ILA/VIO cores)

While many editors support arbitrary ordering, Modelsim enforces strict declaration-before-use. Maintaining this sequence ensures maximum compatibility across all simulation and synthesis tools.

Content Layer

Content comments use dashes to partition individual elements within sections:

// ---------------------------------------------------------- // Control state machine // ----------------------------------------------------------

Content layer annotations serve multiple purposes:

Grouping related functionality spanning multiple structural blocks Numbering items for quick navigation (e.g., // ----- 1. FIFO Buffer -----) Visual separation of logical functional groups

File Header Template

A standardized file header template provides project metadata and revision history:

/* ******************************************************************************

• Company: Your Company Name
• Engineer: Engineer Name
• Create Date: 2024/03/24 12:39:43
• Design Name:
• Module Name: design_module
• Project Name:
• Target Devices: ZYNQ7010 | XCZU2CG | Kintex7
• Tool Versions: 2021.1 || 2022.2
• Description:

•       *
  
  

• Dependencies:

•       *
  
  

• Revision: 0.01
• Revision 0.01 - File Created
• Additional Comments:
• ****************************************************************************** */

Port Documentation with TerosHDL

TerosHDL extends Verilog comments with special documentation markers. Ports prefixed with //! are extracted into generated documentation:

module communication_core #( parameter DATA_WIDTH = 8, parameter BUFFER_SIZE = 16 ) ( // System signals input wire clk, input wire rst_n,

//! @virtualbus uart_interface @dir out
output wire uart_tx,      //! Transmit data line
input  wire uart_rx,      //! Receive data line
//! @end

//! Status outputs
output wire [3:0] status_flags,  //! Error and status indicators

//! @dir in
input  wire [DATA_WIDTH-1:0] data_in //! Input data bus
//! @end

);

Documentation vs. Inline Comments

The distinction between //! and // is essential:

//! - Extracts to external documentation // - Remains inline for code readability only

Best practice: Reserve //! for interface contracts, parameter descriptions, and behavioral specifications. Use plain // for implementation notes and logic explanations.

Markdown Extensions in Code

Combining multi-line and single-line comments enables Markdown-style documentation within Verilog files:

/*

Complex Algorithm Description

The interpolation formula:

result = (a * x + b * y) / denominator

TerosHDL Extensions

Waveform Diagram Insertion

TerosHDL supports WaveDrom-compatible timing diagram specification using JSON format:

//! { signal: [ //! { name: "clock", wave: "P......." }, //! { name: "data", wave: "x.====.x", data: ["IDLE", "REQ", "ACK", "DONE"] }, //! { name: "valid", wave: "0.1...0." } //! ], //! head:{ //! text:'Timing Diagram', //! tick:0, //! every:2 //! }}

WaveDrom uses these waveform characters:

P - Clock pulse 0 / 1 - Low / High stable x - Unknown/High-impedance = - Data valid (mid-cycle transition) . - No transition

State Machine Documentation

TerosHDL automatically recognizes and diagrams state machines enclosed in special comments:

/* @begin state machine */ // State identifiers localparam S_IDLE = 4'b0000; localparam S_READ = 4'b0001; localparam S_WRITE = 4'b0010; localparam S_BUSY = 4'b0100;

// State register reg [3:0] state_q = S_IDLE;

// State transition logic always @(posedge clk) begin if (!rst_n) begin state_q <= S_IDLE; end else begin case (state_q) S_IDLE: begin if (start_cmd) state_q <= S_READ; end S_READ: begin if (fifo_empty) state_q <= S_BUSY; else state_q <= S_WRITE; end default: state_q <= S_IDLE; endcase end end /* @end state machine */

The plugin generates a state transition diagram showing all states, their encodings, and conditional jump paths.

Generated Documentation

TerosHDL exports documentation in HTML format, including:

Module interface specifications Parameter definitions with descriptions Port listings with direction and purpose Embedded waveform diagrams Auto-generated state machine diagrams Timing specifications from WaveDrom blocks

Additional Features

Beyond documentation generation, TerosHDL provides:

Schematic view generation from RTL code Simulation template scaffolding Syntax validation and linting Cross-reefrence navigation