auto-doc-cpsource

A Claude Code skill that automatically documents C source code files according to a comprehensive documentation standard.

What It Does

When you invoke /auto-doc-cpsource on a .c or .h file, it reads the code, identifies undocumented items, and adds documentation following a three-layer standard:

• File headers -- module purpose, dependencies, notes, author
• Function documentation -- description, arguments, return values, errors, side effects
• Struct and enum documentation -- field-level comments with ownership and units
• Inline comments -- only where needed for complex logic, magic numbers, security checks, workarounds
• Ownership and lifetime rules -- who allocates, who frees, borrowed vs. owned pointers
• Thread safety notes -- safe or not, required locks, lock ordering

Format

• .h files and public APIs use Doxygen format (@brief, @param[in], @return, etc.)
• .c files use the standard block format (Function, Description, Input Arguments, Returns, etc.)
• Both formats are accepted in either file type

What It Won't Do

• Change functional code (comments and documentation only)
• Overwrite existing correct documentation
• Add comments that restate obvious code
• Rename functions or variables (it will suggest renames in the summary)

Requirements

• Claude Code CLI or IDE extension

Installation

git clone https://github.com/cpsource/auto-doc-cpsource.git
cd auto-doc-cpsource
./install.sh

This copies the skill files to ~/.claude/skills/auto-doc-cpsource/. Restart Claude Code after installing.

Manual Installation

mkdir -p ~/.claude/skills/auto-doc-cpsource/references
cp SKILL.md ~/.claude/skills/auto-doc-cpsource/
cp references/* ~/.claude/skills/auto-doc-cpsource/references/

Usage

Inside Claude Code, run:

/auto-doc-cpsource src/user_lookup.c

To document all C files in a directory:

/auto-doc-cpsource src/network/

To document a header file:

/auto-doc-cpsource include/api.h

If you run /auto-doc-cpsource with no arguments, it will ask which file(s) to document.

Example Output

After documenting a file, the skill reports a summary:

Documented src/user_lookup.c:
  - File header: added
  - Functions documented: 5 (find_user_by_id, validate_user, load_users, free_user_table, hash_user_id)
  - Structs documented: 2 (UserRecord, UserTable)
  - Enums documented: 1 (UserStatus)
  - Inline comments added: 3 (magic number, loop invariant, ownership note)
  - Ownership rules documented: 2 (load_users return, free_user_table)
  - Thread safety: noted module as not thread-safe in file header

Questions for verification:
  1. find_user_by_id: Is the returned pointer guaranteed valid until table destruction?
  2. load_users: Should this function be considered thread-safe if called with separate tables?

Documentation Standards

The skill enforces three complementary standards (included in the references/ directory):

Document	Description
Documentation Standard	Core rules -- file headers, function blocks, inline comments, ownership, thread safety
Doxygen Specification	Doxygen-compatible format for public APIs (@brief, @param, @return, etc.)
Full Specification	Complete practical spec covering branches, switches, loops, magic numbers, naming

Key Principles

1. Explain why, not what -- comments describe intent, assumptions, and constraints
2. Good naming comes first -- documentation supplements clear names, not replaces them
3. Be precise about return values -- list each return code with its meaning
4. Document ownership -- every pointer parameter and return value needs ownership rules
5. Comment complex logic only -- no narration of obvious code

Uninstall

rm -rf ~/.claude/skills/auto-doc-cpsource

License

See LICENSE for details.