cpp-interface-purpose-comments

Cpp Interface Purpose Comments

Overview

Add comment with following template:

/* 
    Purpose : (mandatory, brief or remark or description, merge with existing if there is)
    Notes : (optional, don't emit this line if empty, merge with existing if there is) 
    Args : (optional, don't emit this line if empty, merge with existing if there is) 
    Return : (optional, don't emit this line if empty, merge with existing if there is) 
*/

directly above each pure virtual method declaration in C++ interface headers.

• Prefer reading knowledges about specified functions from serena's memories first.
• Prefer multi-line comments.
• Keep everything as SHORT as possible.
• The comments should ALWAYS be in English.
• If there is ALREADY Purpose or comment for the interfaces there, use the existing purpose or comment instead of generating our own.

Workflow

1. Confirm scope: target files or directories, desired comment text, and whether to skip existing comments.
2. Prefer scripted pass using scripts/add_pure_virtual_purpose_comments.py with --dry-run first.
3. Review changes and handle any missed edge cases with manual edits.
4. Package the skill when stable.

Scripted workflow (preferred)

Run a dry run:

python scripts/add_pure_virtual_purpose_comments.py --dry-run --globs "*.h,*.hpp" <path>

Apply edits:

python scripts/add_pure_virtual_purpose_comments.py --globs "*.h,*.hpp" <path>

Script behavior

• Detect statements containing virtual and = 0; with a function-like (...) pattern.
• Support multi-line declarations until the first ;.
• Skip insertion if the nearest non-empty line above is a comment, unless --force.
• Preserve existing line endings and indentation.

Parameters

• --comment: override the default comment text.
• --globs: comma-separated patterns for recursive directory scans.
• --dry-run: report changes without writing files.
• --force: insert even if a comment exists immediately above.

Manual fallback

• Insert the comment directly above the first line of the declaration using the same indentation.
• For macro-heavy or generated code, prefer targeted edits to avoid unintended changes.