Skip to content

Commentator Agent

The Commentator Agent analyzes existing RTL source code and produces clear, high-quality comments that explain functionality, interfaces, and design intent. It is designed to be codebase-aware and safe: rather than commenting a file in isolation, it discovers relevant modules and hierarchies across your project, and it rigorously verifies that adding comments does not change the underlying logic.

Key Features

  • Project-Aware Commenting: Goes beyond single-file analysis by discovering instantiated submodules and related RTL files, ensuring comments reflect the true design context.
  • Logic-Preserving Safety Checks: Uses Abstract Syntax Tree (AST) comparison to guarantee that commenting never alters functionality. The commented output is accepted only if it is bit‑exact with the original logic.
  • Seamless In-Place Updates: Optionally writes comments directly back to the source file, making it easy to integrate into existing workflows.
  • Custom Documentation Rules: Respects project-specific commenting guidelines defined in a NEX.md file at the project root.
  • IDE Integration: Available directly in VS Code via the command palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux). Select NEX: Suggest Comments to run the Commentator on the currently open file without leaving your editor.

Command Options

The Commentator agent supports the following command-line options:

Option Shorthand Description
--input-file -f Required. Path to the file to be commented.
--inplace -i Writes comments directly back to the input file. If omitted, output is printed to the terminal.
--json-output Emits structured JSON output (status, language, code) for use in scripts and tooling.

Incompatible arguments

The --json-output and --inplace arguments are mutually exclusive.

Usage

Use the Commentator agent through the NEX CLI by specifying --agent=commentator.

Basic Command

Preview comments for a specific file without modifying it:

nex --agent=commentator --input-file=src/cpu/alu.sv

The commented code is printed to the terminal with syntax highlighting.

Applying Changes In-Place

Apply the generated comments directly to the source file: 

nex --agent=commentator --input-file=src/cpu/alu.sv --inplace

JSON Output (For Tooling)

For automation, CI pipelines, or editor integrations, you can request structured JSON output: 

nex --agent=commentator --input-file=src/cpu/alu.sv --json-output

Configuration

You can customize the Commentator to match your project's documentation style and conventions.

Place a NEX.md file in your project root to define guidance such as tone, level of detail, naming conventions, or areas of focus. The Commentator reads this file and incorporates your instructions into its system prompt when generating comments.

Example

See an example NEX.md file here.

Tutorial

Step-by-step usage examples and guided walkthroughs are available in the GitHub tutorial repository.