DoxNet

Names, directions, widths and defaults come from the code. A comment only has to say what the code can't: what a port is for. Comments can sit in front of a declaration (/** */, ///) or behind it (///<), or be written as tags in the unit comment.

Namen, Richtungen, Breiten und Standardwerte kommen aus dem Code. Ein Kommentar muss nur sagen, was der Code nicht kann: wofür ein Port da ist. Kommentare können vor einer Deklaration stehen (/** */, ///), dahinter (///<) oder als Tags im Kommentar der Einheit.

/**
 * @brief Single-clock FIFO with registered outputs.
 *
 * Write and read may happen in the same cycle.
 * @note DEPTH must be a power of two.
 */
module sync_fifo #(
  parameter int WIDTH = 8,   ///< Data width in bits
  parameter int DEPTH = 16   ///< Number of entries
) (
  input  logic             clk,      ///< Clock
  input  logic             rst_n,    ///< Asynchronous reset, active low
  input  logic [WIDTH-1:0] wr_data,  ///< Data to push
  output logic             full      ///< No free entry left
);

The main output is a single HTML file with all styles and scripts inlined. It can be opened from disk, attached to a ticket or published on GitHub Pages. The screenshots show the UART example from the repository.

Die Hauptausgabe ist eine einzelne HTML-Datei, in der alle Styles und Skripte eingebettet sind. Sie lässt sich direkt von der Festplatte öffnen, an ein Ticket hängen oder auf GitHub Pages veröffentlichen. Die Screenshots zeigen das UART-Beispiel aus dem Repository.

unitEinheit overviewÜbersicht

$ pip install git+https://github.com/BTFLV/DoxNet.git

# document every .v/.sv/.vh/.svh below rtl/
$ doxnet --input rtl --output build/docs

# with macros and include paths, as for the simulator
$ doxnet --filelist sim/files.f -D SYNTHESIS --incdir rtl/include --output build/docs

# check only: all units documented, 90 % of ports, no warnings
$ doxnet --input rtl --check --strict --min-port-coverage 90 --fail-on-warnings

For anything beyond a quick run, the options go into a config file. JSON and TOML work, as does a [tool.doxnet] section in pyproject.toml.

Für alles über einen schnellen Lauf hinaus kommen die Optionen in eine Konfigurationsdatei. JSON und TOML funktionieren, ebenso ein Abschnitt [tool.doxnet] in der pyproject.toml.

{
  "title": "UART example",
  "input": "rtl",
  "include_dirs": ["rtl/include"],
  "output": "build/docs",
  "html_file": "index.html",
  "min_coverage": 100,
  "min_port_coverage": 100,
  "fail_on_warnings": true
}

Files come from a directory, an explicit list in the config, or a simulator filelist. `ifdef, `ifndef, `elsif and `else are evaluated, so code in an inactive branch doesn't show up in the documentation or count towards coverage.

Dateien kommen aus einem Verzeichnis, einer expliziten Liste in der Konfiguration oder einer Simulator-Filelist. `ifdef, `ifndef, `elsif und `else werden ausgewertet, sodass Code in einem inaktiven Zweig weder in der Dokumentation auftaucht noch zur Abdeckung zählt.

# comments start with # or //
+incdir+include+../common/include
+define+SYNTHESIS+BUS_WIDTH=64
$PROJECT_ROOT/rtl/top.sv
${IP_ROOT}/fifo/fifo.sv
-f ../common/common.f

Every documented name is matched against the parsed declaration. When a port is renamed but its comment isn't, the run says so, and the coverage gate catches the now undocumented port:

Jeder dokumentierte Name wird mit der geparsten Deklaration abgeglichen. Wird ein Port umbenannt, sein Kommentar aber nicht, meldet der Lauf das, und die Abdeckungsschwelle fängt den nun undokumentierten Port ab:

$ doxnet -c doxnet.json --check
WARNING: uart_tx.sv:15: DOC001: @port refers to unknown port busy
INFO: units coverage: 5/5 (100.0%)
INFO: ports coverage: 19/20 (95.0%)
ERROR: ports coverage 95.0% is below the required 100.0%
INFO: parameters coverage: 7/7 (100.0%)
# exit code 2

The repository is a GitHub Action. It installs DoxNet and reports diagnostics as annotations on the affected lines of a pull request.

Das Repository ist zugleich eine GitHub Action. Sie installiert DoxNet und meldet Diagnosen als Anmerkungen an den betroffenen Zeilen eines Pull Requests.

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: BTFLV/DoxNet@v3.0.0
        with:
          args: --config doxnet.json --output build/hdl-docs --no-pdf
      - uses: actions/upload-artifact@v4
        with:
          name: hdl-docs
          path: build/hdl-docs

There's also a pre-commit hook that runs doxnet --check, and the same command works in GitLab CI or anywhere else with Python.

Außerdem gibt es einen pre-commit-Hook, der doxnet --check ausführt, und derselbe Befehl funktioniert in GitLab CI oder überall sonst, wo Python läuft.

repos:
  - repo: https://github.com/BTFLV/DoxNet
    rev: v3.0.0
    hooks:
      - id: doxnet
        args: [--config, doxnet.json]

For an existing, mostly undocumented code base, start with thresholds slightly below the current coverage and raise them over time. fail_on_warnings is worth enabling early: a stale comment is cheap to fix when it appears.

Bei einer bestehenden, größtenteils undokumentierten Codebasis mit Schwellen knapp unter der aktuellen Abdeckung starten und sie mit der Zeit anheben. fail_on_warnings lohnt sich früh: Ein veralteter Kommentar ist billig zu beheben, wenn er gerade entsteht.

DoxNet parses declarations; it doesn't elaborate the design. Expressions are shown as written, so [WIDTH-1:0] stays symbolic, macros aren't expanded and generate loops aren't unrolled. It covers the constructs found in typical RTL but isn't a replacement for a compiler.

DoxNet parst Deklarationen, elaboriert das Design aber nicht. Ausdrücke werden so gezeigt, wie sie geschrieben sind: [WIDTH-1:0] bleibt symbolisch, Makros werden nicht expandiert und Generate-Schleifen nicht aufgerollt. Es deckt die Konstrukte typischen RTL-Codes ab, ersetzt aber keinen Compiler.