AI Docstring Generator (VS Code Extension)

Generate docstrings/comments for selected code using an OpenAI-compatible Chat Completions API, then watch the result stream directly into your file in real time.

Features

• Streaming output: tokens appear word-by-word in the editor as they are generated — no waiting for the full response
• Auto-detect enclosing block: place the cursor anywhere inside a function or class — no manual selection needed
• Docstring style picker: choose Google, NumPy, reStructuredText, or auto style (Python only)
• Generate docstrings from selection: select any code block and run Generate Docstring
• Provider-agnostic: works with any service that supports POST /chat/completions in an OpenAI-compatible format
• Cancelable requests: cancel from the progress notification to abort mid-stream
• Context menu integration: right-click on a selection → Generate Docstring

Install / Run (development)

This repo is a VS Code extension project.

1. Install dependencies:

npm install

2. Build once:

npm run compile

3. Run the extension:

• In VS Code, press F5 (or fn+F5 on macOS) to open an Extension Development Host
• In the dev host, open a file and run Generate Docstring

Usage

1. Optional: select a function or class in the editor. If nothing is selected, the extension automatically detects the enclosing function/class at the cursor.
2. Run AI Docstring Generator: Generate Docstring from:
   • Keyboard shortcut: Cmd+Shift+D (macOS) / Ctrl+Shift+D (Windows/Linux)
   • Command Palette (Cmd/Ctrl+Shift+P) → search "Generate Docstring"
   • Editor right-click menu (only shows when there is a selection)
3. Watch the docstring stream in above the selected code in real time.

Configuration

Settings live under aiDocstringGenerator (VS Code Settings UI: search "AI Docstring Generator").

Required

• aiDocstringGenerator.apiKey: API key for your provider

Common

• aiDocstringGenerator.apiBaseUrl: base URL for an OpenAI-compatible API (default: https://api.openai.com/v1)

• aiDocstringGenerator.model: model name (provider-specific)

• aiDocstringGenerator.temperature: sampling temperature (default: 0.2)

• aiDocstringGenerator.maxTokens: max tokens for the generated docstring (default: 512; increase to 1024+ for complex classes or modules)

• aiDocstringGenerator.docstringStyle: docstring format style (default: auto)

  Value	Description
  auto	Model follows language conventions automatically
  google	Google Style — Args:, Returns:, Raises: sections (Python only)
  numpy	NumPy/SciPy Style — Parameters\n----------, Returns\n------- (Python only)
  rest	reStructuredText / Sphinx — :param:, :type:, :returns:, :rtype: (Python only)

  Style variants only affect Python files. All other languages always use auto.

Provider examples

OpenAI

• aiDocstringGenerator.apiBaseUrl: https://api.openai.com/v1
• aiDocstringGenerator.model: e.g. gpt-4o-mini

Google Gemini (OpenAI compatibility)

Gemini offers an OpenAI-compatible endpoint.

• aiDocstringGenerator.apiBaseUrl: https://generativelanguage.googleapis.com/v1beta/openai/
• aiDocstringGenerator.model: e.g. gemini-3-flash (choose a model supported by the compatibility layer)

Commands

• ai-docstring-generator.generateDocstring: Generate Docstring

Project structure

• src/extension.ts: command registration, editor integration, streaming insertion, and block auto-detection
• src/openaiCompat.ts: OpenAI-compatible client (streaming + non-streaming) + settings loader
• src/docstring.ts: prompt/messages builder with docstring style support
• esbuild.js: bundles the extension to dist/extension.js

Scripts

• npm run compile: typecheck + lint + bundle
• npm run watch: watch mode (tsc + esbuild)
• npm test: run extension tests
• npm run vsce:package: package the extension into a .vsix file
• npm run vsce:publish: publish to the VS Code Marketplace

Security notes

• Do not commit API keys. Use VS Code settings for aiDocstringGenerator.apiKey.
• If you accidentally expose a key: revoke/regenerate it immediately.

License

MIT