Source Doc
A VS Code extension that explains source code line-by-line, block-by-block, or all at once via CodeLens markers, powered by GitHub Copilot.
Features
- CodeLens markers appear above every function, class, method (block mode), every non-empty line (line mode), or just a single file-level lens (file mode).
- Click a lens to get a concise, one-sentence AI explanation generated by GitHub Copilot — no API key required.
- Explain file — explain every non-noise line in the current file in parallel with a single click.
- Explanations render as inline ghost text (italic comment) directly after the target line.
- Hover over truncated ghost text to see the full explanation in a tooltip.
- Toggle mode between
block, line, both, file, and none via the status bar or command palette.
- Generated files are skipped — no lenses on
*.d.ts, *.g.cs, *.min.js, etc.
- LRU cache — repeated requests for the same code never hit the API twice.
- Supports TypeScript, TSX, JavaScript, JSX, C#, XAML.
Requirements
- VS Code 1.90 or newer
- GitHub Copilot extension installed and signed in
Getting Started
- Clone / open this folder in VS Code.
- Run
npm install then press F5 to launch the Extension Development Host.
- Open any supported file (
.ts, .tsx, .js, .jsx, .cs, .xaml).
- CodeLens markers appear above each block — click
$(comment) Explain block, $(comment) Explain line, or $(comment) Explain file.
- Ghost text with the explanation appears at the end of the line.
Commands
| Command |
Description |
Source Doc: Explain Block |
Explain the function / class under the lens |
Source Doc: Explain Line |
Explain a single line |
Source Doc: Explain File (all lines) |
Explain every non-noise line in the file in parallel |
Source Doc: Toggle Mode |
Cycle through block → line → both → file → none |
Source Doc: Clear All Explanations |
Remove all ghost text from the active workspace |
Source Doc: Refresh CodeLenses |
Force a full refresh of all CodeLens markers |
Settings
| Setting |
Type |
Default |
Description |
sourceDoc.enabled |
boolean |
true |
Enable or disable all CodeLens markers |
sourceDoc.mode |
"block" | "line" | "both" | "file" | "none" |
"block" |
Granularity of CodeLens markers |
sourceDoc.languages |
string[] |
["typescript","typescriptreact","javascript","javascriptreact","csharp","xaml"] |
Language IDs to activate on |
sourceDoc.modelFamily |
string |
"gpt-4o" |
GitHub Copilot model family to use |
sourceDoc.maxExplanationLength |
number |
160 |
Max characters of ghost text (40–400) |
Modes
| Mode |
Behaviour |
block |
One lens per function / class / method (default) |
line |
One lens per non-noise line |
both |
Both block-level and line-level lenses |
file |
Only the $(comment) Explain file lens at the top of the file |
none |
No lenses at all |
How It Works
Open file
│
▼
CodeLensProvider.provideCodeLenses()
│ isGeneratedFile() → skip *.d.ts, *.g.cs, *.min.js …
│ mode === 'none' → return []
│
├─ always: file-level "Explain file" lens at line 0
├─ block mode → executeDocumentSymbolProvider (LS symbols)
│ └─ fallback: regex detection + retry in 2.5 s
└─ line mode → iterate non-noise lines
│
▼
User clicks lens
│
├─ explainLine / explainBlock
│ └─ ExplanationProvider.explain(code, languageId)
│ ├─ cache hit → return immediately
│ └─ cache miss → vscode.lm.selectChatModels({ vendor: 'copilot' })
│ stream response
│
└─ explainFile
└─ Promise.allSettled(lines.map(line => explain(line)))
└─ decorationManager.setExplanation() as each result arrives
│
▼
DecorationManager.setExplanation(editor, line, text)
└─ TextEditorDecorationType `after: { contentText: " // ..." }`
HoverProvider shows full text when truncated
XAML support
For .xaml files the extension uses a PascalCase element regex
(<Grid, <StackPanel, <Style, …) and feeds Copilot up to 30 lines
of element content as context, since .xaml language servers don't
always expose document symbols.
Development
# Install dependencies
npm install
# Compile once
npm run compile
# Compile in watch mode (used by the F5 debug task)
npm run watch
Press F5 in VS Code to open the Extension Development Host with the extension loaded.
License
MIT
| |
