Code Comment Assistant

A production-ready VS Code extension that enforces documentation standards across JavaScript, TypeScript, React, Next.js, Node.js — and 36 languages in total, including PHP, Blade, Twig, HTML, Vue, Svelte, SQL, Python, Java, C/C++, C#, Go, Rust, CSS/SCSS, Ruby, YAML and more.

It validates file headers and function documentation, surfaces issues in the Problems panel, and offers one-click quick fixes and commands to generate the missing documentation. Function detection uses the Babel AST for JavaScript/TypeScript/React and dedicated language scanners for PHP, Python, Java and Go — never blind regex. Descriptions can optionally be written by AI (Anthropic, OpenAI, OpenRouter, Google Gemini or NVIDIA — Gemini and NVIDIA have free tiers).

Requirements

• VS Code ^1.85.0 (or a compatible editor such as Cursor / VS Codium).
• Git on PATH (optional) — used to auto-detect the developer name and for git-blame attribution.
• An AI provider API key (optional) — only if you enable AI-generated descriptions (codeDoc.ai.enabled).
• Node.js 18+ — only if you build the extension from source.

Quick start

1. Install the extension (from the Marketplace or a packaged .vsix).
2. Open any supported file — documentation gaps immediately appear in the Problems panel and as a bottom-right warning toast.
3. Press Ctrl+. on a highlighted line and choose Generate Documentation, or run Code Comment: Generate Missing Documentation to fix the whole file.
4. (Optional) To let AI write the descriptions: run Code Comment: Set AI API Key, pick a provider with Code Comment: Select AI Provider, then enable codeDoc.ai.enabled (or flip everything from Open Settings Dashboard).

Features

1. File header validation

Every source file must begin with a documentation block:

/**
 * File Name: user.tsx
 * Description: Displays user dashboard data and analytics.
 * Developer: Whitelabel IQ
 * Created Date: 2026-06-10
 * Last Modified: 2026-06-10
 */

Validated fields: File Name, Description, Developer, Created Date, Last Modified. Any missing field raises a warning diagnostic. The required fields and their order are configurable via codeDoc.headerFields.

2. Function documentation validation

Every function must be preceded by a JSDoc block:

/**
 * Fetches user dashboard data.
 *
 * @author Whitelabel IQ
 * @created 2026-06-10
 * @modified 2026-06-10
 *
 * @param userId
 * @returns DashboardData
 */
async function getDashboardData(userId) {}

Required (validated): Description, @author, @created (a legacy @date tag is accepted in place of @created). The remaining generated fields — @modified, @version, @param, @returns, @throws — are emitted from the code when present but are never flagged as missing. Tune the set with codeDoc.functionFields. Detected via AST:

• function declarations
• arrow functions
• exported functions
• async functions
• class methods
• React functional components

3. Auto-detected developer name

Resolved in priority order:

1. codeDoc.developerName setting (when set, overrides git)
2. git config user.name
3. Unknown Developer (fallback)

Set it interactively with Code Comment: Set Developer Name.

4. Diagnostics

Warnings appear in the Problems panel, e.g. "Missing file documentation header.", "Missing Developer field in file documentation header.", "Function getUsers missing documentation.", "Function getUsers missing @author.", "Function getUsers missing @created." A description made only of a placeholder word (see codeDoc.placeholderBlocklist, e.g. todo, tbd, fixme) is reported as an Information-level diagnostic.

4a. Warning notification + navigable list

When you open a file with documentation gaps, a warning toast appears in the bottom-right — e.g. "Code Comment: 5 comments are missing in UserController.php." — with three actions: Show List, Generate with Comment (uses AI descriptions), and Generate without Comment (structure only). Show List opens a clickable list of every undocumented function/field; selecting one jumps straight to it. A status-bar item also shows the current file's issue count. Run the list anytime with Code Comment: List Missing Documentation. Toggle the toast with codeDoc.showWarningPopup.

5. Quick fixes

A Generate Documentation quick fix (lightbulb / Ctrl+.) resolves any diagnostic by inserting or repairing the relevant block. Existing description/@author/@created values are preserved when repairing.

6. Commands

Open the Command Palette (Ctrl+Shift+P) — all commands are under the Code Comment category:

• Code Comment: Generate File Header
• Code Comment: Generate Function Documentation
• Code Comment: Generate Missing Documentation
• Code Comment: List Missing Documentation
• Code Comment: Scan Workspace Documentation Coverage
• Code Comment: Set Developer Name
• Code Comment: Set AI API Key (for AI descriptions)
• Code Comment: Clear AI API Key
• Code Comment: Select AI Provider
• Code Comment: Select AI Model
• Code Comment: Show AI Provider & Model
• Code Comment: Open Settings Dashboard
• Code Comment: Show Documentation Warning

Generate/list commands are also available from the editor right-click menu (for supported languages).

7. Auto header for new files

Creating an empty .js / .jsx / .ts / .tsx file automatically inserts a pre-filled header (file name, developer, current date). Toggle with codeDoc.enableAutoHeader.

8. Auto "Last Modified" / @modified / @version

Saving a documented file refreshes the header Last Modified date and each function's @modified — but only on a meaningful code change (whitespace/blank-line edits are ignored). @version increments once per editing session, when the file is closed. Toggle date refresh with codeDoc.enableAutoModifiedDate.

8a. AI-generated descriptions (opt-in)

Enable codeDoc.ai.enabled to have an AI model write the documentation from the actual code. When on, the generate commands (file header / function / missing) send the relevant snippet to the configured provider's API and fill in a purpose-focused Description, per-@param reasons, a concise @returns outcome, and @throws (only when the code actually throws/catches). The prompt is tuned to explain why over what and to avoid inventing fields or exceptions.

• Choose your provider with codeDoc.ai.provider. Five are supported: Anthropic (anthropic), OpenAI (openai), OpenRouter (openrouter), Google Gemini (gemini), and NVIDIA (nvidia). OpenRouter, Gemini and NVIDIA all offer free tiers (rate-limited, not unlimited).

• Set your key once with Code Comment: Set AI API Key (stored in VS Code SecretStorage — never in settings or files; each provider's key is stored separately). Clear it with Code Comment: Clear AI API Key.

• Choose the model per provider:

  • codeDoc.ai.model — Anthropic (default claude-opus-4-8)
  • codeDoc.ai.openaiModel — OpenAI (default gpt-4o-mini)
  • codeDoc.ai.openRouterModel — OpenRouter (default meta-llama/llama-3.3-70b-instruct:free)
  • codeDoc.ai.geminiModel — Gemini (default gemini-2.0-flash)
  • codeDoc.ai.nvidiaModel — NVIDIA (default meta/llama-3.3-70b-instruct). NVIDIA's picker shows only models actually served on the hosted chat endpoint (many listed models 404 otherwise).

  The *-mini / haiku / flash / :free models are cheaper/faster for bulk runs. Pick the model interactively with Code Comment: Select AI Model, which can load your account's live model list. For NVIDIA the live list is filtered to text chat models only (embedding, vision, safety and other non-chat models are hidden so you can't pick one that won't work).

• Automatic model fallback: if the active model hits its usage/rate limit (429/402), the extension transparently switches to another model and keeps going — same free/paid tier on OpenRouter, the provider's other models elsewhere — for the rest of the session (your saved model is unchanged). A transient 503 ("busy"/overloaded) triggers a retry and, if needed, a switch to another model without permanently blacklisting the busy one. Models that reject a separate system role (some NVIDIA models) are handled automatically by folding the system prompt into the user message.

• Cross-provider fallback (codeDoc.ai.crossProviderFallback, on by default): when every model of the active provider is rate-limited/busy, generation falls back to another provider you've set a key for (free-first: NVIDIA → Gemini → OpenRouter → OpenAI → Anthropic), pooling your free tiers so limits rarely break a run. Your saved provider is unchanged. On fallback, code is sent to the alternate provider you configured.

• AI runs only on explicit commands — never while hovering quick fixes or typing — and shows a progress notification. (The optional codeDoc.ai.refreshOnChange / refreshOnSave settings can additionally re-generate a changed function's description on save; both are off by default and call the provider, so costs apply.)

• Privacy: with this enabled, source code is sent to whichever provider you configure (Anthropic, OpenAI, OpenRouter, Google or NVIDIA). It is off by default; leave it off for code that must not leave the machine.

8b. Settings Dashboard

Run Code Comment: Open Settings Dashboard (or click the gear icon in the editor title bar, or the ✨ AI: status-bar item) to open a visual panel for all settings — provider/model selection with live model dropdowns and a Test connection button, API key entry, header/function fields, validation options, refresh-on-change mode, git-blame attribution and the language list — without editing settings.json by hand. Changes are written to global (user) settings, and an "Apply to all projects" banner promotes any workspace-pinned setting to global.

8b-i. Status-bar items

• ✨ AI: <provider> — shows the active AI provider; click for a quick menu (open dashboard, switch provider/model, set key, enable/disable).
• ⚠ N doc issues / ✓ Docs OK — shows the open file's documentation status; click to open the searchable list of gaps.

8c. Workspace coverage scan

Code Comment: Scan Workspace Documentation Coverage walks the workspace (honouring codeDoc.scanExclude) and reports overall documentation coverage. Toggle the command with codeDoc.enableWorkspaceScan.

8d. Git-blame attribution (opt-in)

With codeDoc.useGitBlame enabled, generated function @author/@date are attributed to the git blame author of the function's line rather than the current developer.

9. Multi-language support

File-header features work across 36 languages, using the correct comment syntax for each:

• Block /** */ — JavaScript, TypeScript, JSX, TSX, PHP, Java, C, C++, C#, Go, Rust, Swift, Kotlin, Scala, Dart, CSS, SCSS, LESS, Groovy, SQL.
• HTML <!-- --> — HTML, Vue, Svelte, XML, Markdown.
• Blade {{-- --}} — Laravel Blade (*.blade.php).
• Twig {# #} — Twig templates.
• Hash # — Python, Ruby, Shell, PowerShell, Perl, R, YAML, Dockerfile, Makefile.

PHP's <?php opening tag is handled automatically (the header goes after it). Function-level validation (per-function docs) runs for JavaScript/TypeScript/React (Babel AST) and for PHP, Python, Java and Go (dedicated line scanners that understand functions/methods, visibility modifiers and parameters). Every other language gets file-header validation. Tune the active set with codeDoc.supportedLanguages.

Scope: validation runs only on the file you have open (its page header and its functions) — the whole-workspace scan is a separate on-demand command. Warnings appear when you open a file and clear when you close its tab.

Settings

A committed project-level .codedocrc (or .codedocrc.json) file can override any of these settings per workspace.

Project structure

src/
├── extension.ts          # entry point / composition root
├── commands/             # command handlers + registration
├── core/                 # UI-free validation core
├── validators/           # file header & function doc validators
├── generators/           # header & function doc text generators
├── diagnostics/          # diagnostic collection manager
├── providers/            # CodeActionProvider (quick fixes)
├── parsers/              # Babel AST + PHP/Python/Java/Go scanners
├── dashboard/            # settings dashboard webview
├── services/             # config, developer, date, documentation, AI, lifecycle
├── utils/                # language, doc-block & editor helpers
└── types/                # shared interfaces & constants

Installation (from source)

npm install
npm run compile

Then press F5 in VS Code to launch an Extension Development Host with the extension loaded.

Build

npm run compile      # one-off TypeScript build to ./out
npm run watch        # incremental rebuilds
npm run lint         # eslint

Package a .vsix

npm install -g @vscode/vsce   # or use the local devDependency
npm run package               # produces code-comment-assistant-1.0.0.vsix

Install the packaged extension:

code --install-extension code-comment-assistant-1.0.0.vsix

Publishing to the Marketplace

The publisher field in package.json is already set to whitelabel-iq.

1. Ensure you have access to the whitelabel-iq publisher at https://marketplace.visualstudio.com/manage and an Azure DevOps Personal Access Token (scope: Marketplace → Manage).
2. Authenticate and publish:

vsce login whitelabel-iq
npm run publish              # or: vsce publish [major|minor|patch]

Note: dependencies (@babel/*, @anthropic-ai/sdk, openai) are intentionally in dependencies (not devDependencies) so vsce bundles them into the published package.

Known limitations

• File-scoped validation. Diagnostics run only on the file you have open; cross-file/whole-project checking is available only via the on-demand Scan Workspace Documentation Coverage command.
• Function-level docs are validated for JavaScript/TypeScript/React, PHP, Python, Java and Go. Other languages get file-header validation only.
• AI descriptions send code off-machine. When codeDoc.ai.enabled is on, the relevant snippet is sent to your chosen provider. It is off by default.
• The language scanners for PHP/Python/Java/Go are line-based (not full parsers); very unusual formatting may occasionally be missed.

Changelog

See CHANGELOG.md for release notes.

License

MIT — see the LICENSE file included with this extension.

Developed by Whitelabel IQ Team