dsh-doxygen

dsh plugin --profile web add dsh-doxygen

doxygen-comment

English | [中文说明](#中文说明)

An agent skill for generating and maintaining Doxygen comments in C/C++

(including Qt) sources. It is not a snippet collection but a pipeline an AI coding assistant can drive

end to end: **read the function signature → generate or complete the comment → mark the comment stale

when the code changes**.

Features

• Locate a function by line number or by name. parse_function.py parses C/C++ signatures with

tree-sitter and prints JSON (function name, return type, parameters and their direction, start line,

signature fingerprint, optional body snippet). Read-only, no side effects.

• Six templates. File header / function / module head / module tail / trailing /**< */ / short

@brief, matching the editor snippet prefixes doxygen_source, doxygen_fun,

doxygen_module_head, doxygen_module_end, doxygen_rear, doxygen_nom.

• Fill in, never rewrite. When a Doxygen block already exists above a function, only the missing

fields are added and the fingerprint is refreshed; existing wording and line order are kept. A file

that already carries an @file block is skipped.

• Signature fingerprint. Every function block ends with @doxygen_sig_fp <16 hex digits>; --scan

compares the current signature against it and marks "signature changed, comment outdated" functions

as stale, which is what makes repository-wide upkeep possible. Pure formatting changes (whitespace,

*/& placement) do not change the fingerprint.

• Nothing is written by default. A diff is printed first; --write applies it while preserving the

target file's CRLF/LF style and its UTF-8 / UTF-8-BOM / GBK encoding.

• Fails fast on a machine without Python. The plugin probes Python 3.10+ and tree-sitter at

registration and puts the verdict at the top of the skill body; on a missing or broken interpreter the

skill instructs the agent to stop and hand over the install steps instead of letting a shell error turn

into a fake "function not found". node scripts/check_env.mjs runs the same probe on demand — it is

plain Node, so it works where Python does not.

• CJK-text friendly. The scripts force UTF-8 output, avoiding the mojibake a GBK Windows console

would otherwise cause.

Repository layout

doxygen-comment/
├── SKILL.md                  # skill body: workflow, script contract, template list
├── README.md                 # this file
├── LICENSE                   # MIT
├── requirements.txt          # Python dependencies
├── package.json              # DSH plugin manifest — declares dsh.bundle
├── cordis.patch.yml          # plugin insert row (id: doxygen-comment, name: dsh-doxygen)
├── index.js                  # registers the bundled skill when installed as a plugin
├── assets/
│   └── cpp.json              # the six templates as editor snippets (optional)
├── references/
│   └── examples.md           # before/after examples, Qt cases, common mistakes
└── scripts/
    ├── parse_function.py     # read: locate a function + parse its signature (no side effects)
    ├── gen_doxygen.py        # write: render / insert / complete / fingerprint / diff / scan
    ├── install_snippets.py   # optional: merge the snippets into a VS Code style IDE
    ├── check_env.mjs         # environment preflight (Node, works without Python)
    └── lib/
        └── env.mjs           # the probe behind check_env.mjs; also used by index.js

Installation

1. Get the source

git clone https://github.com/FantastyQAQ/dsh-doxygen.git

The repository is named dsh-doxygen while the skill is named doxygen-comment: when you drop it into

a skills directory, name the directory doxygen-comment.

2. Install it

Two ways in — as a DSH plugin bundle, or by copying the folder into a skills directory.

As a DSH plugin. The repository root declares dsh.bundle, so it installs like any other plugin:

dsh plugin --profile desktop add github:FantastyQAQ/dsh-doxygen

desktop is the profile the desktop app uses — swap in your own profile name (desktop+office, etc.).

The --profile flag is required by current hosts (0.2.1 and newer); dsh plugin add ... alone fails

with required option '--profile <name>' not specified.

index.js registers SKILL.md as the doxygen-comment skill and resolves ${SKILL_DIR} for you,

so no path guessing is needed.

By copying the folder. The directory is self-contained; the scripts contain no

project-specific paths:

Host · Skills directory

DeepSeek Harness · ~/.dsh/skills/doxygen-comment/

Claude Code · ~/.claude/skills/doxygen-comment/, or a project's .claude/skills/

CodeBuddy CN / WorkBuddy · ~/.codebuddy/skills/doxygen-comment/, ~/.workbuddy/skills/doxygen-comment/

# e.g. install for Claude Code at user level
git clone https://github.com/FantastyQAQ/dsh-doxygen.git "$env:USERPROFILE\.claude\skills\doxygen-comment"

3. Dependencies

Requires Python 3.10+; install the C/C++ parser with pip install tree-sitter tree-sitter-cpp:

pip install tree-sitter tree-sitter-cpp
# or the version-constrained install from this repo:
pip install -r requirements.txt

Tested with tree-sitter 0.26.0 + tree-sitter-cpp 0.23.4; the scripts support the Language/Parser

construction API both before and after 0.22. On Windows, always type python (python3 is an alias

trap in some environments).

When Python is missing, the plugin says so instead of failing mid-command. The bundle probes the

machine once when it registers the skill and puts the verdict at the top of the skill body; a failing

verdict tells the agent to stop and hand the install steps to you. The probe is plain Node (Node ships

with DSH), so it can report "no Python" on the very machines where no Python exists:

node scripts/check_env.mjs           # human readable, exit 0/2/3
node scripts/check

…(truncated)