Making Documentation Visible Again
The story behind the VS Code extension that turns JSDoc into contextual, readable, first-class documentation.
Context: I built a VS Code extension that makes JSDoc documentation readable and visually distinct inside the editor. Check it out at:
1. Why This Extension Exists
This extension was born out of a very practical problem encountered while working on a real project with heavy use of coding agents.
When working with AI coding agents, one thing becomes immediately clear:
they benefit enormously from context. Not just types, not just function signatures, but why things exist, how different pieces interact, and what assumptions or quirks the system relies on.
1.1 Starting point: documentation next to source
My first attempt to solve this was to place Markdown documentation files right next to the source code they described. The idea was simple and principled:
Documentation should live close to the code it explains.
Tests live next to code, so documentation should too.
Large, centralized documentation repositories tend to drift or get ignored.
This worked reasonably well for coding agents. They could read those Markdown files and gain the necessary context to make better decisions.
However, this approach had a clear downside.
1.2 The problem with separate files
For human developers, having documentation in separate Markdown files turned out to be suboptimal:
It’s easy to miss that the files exist at all.
They don’t naturally appear in the flow of reading code.
Developers tend to focus on
.ts/.jsfiles and ignore adjacent docs unless explicitly told to read them.
In practice, this meant that:
AI agents benefited from the documentation.
Human developers often didn’t.
That asymmetry was a problem.
1.3 Moving documentation even closer: JSDoc
The next step was to move documentation directly into the source files, using JSDoc comments.
Importantly, this was not JSDoc used “by the book”.
This is internal documentation, not public API documentation.
I am not using JSDoc to describe parameters, return types, or function signatures.
TypeScript already does that, and the implementation is always available.
This is not about generating reference docs.
Instead, JSDoc is used as a structured container for contextual documentation, such as:
How a product works at a higher level
How different functions or modules interact
Design decisions and trade-offs
Known quirks or non-obvious behavior
Any context that helps understand why the code is the way it is
This worked extremely well for coding agents.
They could now see the documentation inline, exactly where it mattered.
1.4 The remaining issue: humans still didn’t read it
Despite being inline, there was still a major problem.
Most code editor themes treat comments — especially block comments — as something to be visually de-emphasized:
Low-contrast colors
Italics
Blended into the background
Visually treated as “noise”
As a result:
The documentation was technically there
It was useful
But it was still easy to ignore
And most developers did ignore it
Unless you hovered a symbol from another file, or deliberately stopped to read comments, the documentation did not stand out as something important.
That was the key insight:
If documentation is important, it should look important.
1.5 The core motivation
The motivation for this extension is therefore simple:
Documentation should be first-class
It should be readable
It should be clearly distinct from executable code
And it should live inside the code, not somewhere else
JSDoc already gives us a natural boundary (/** ... */) for “this is documentation”.
What was missing was a way to make that boundary visually and semantically meaningful in the editor.
That gap is exactly what this extension aims to fill.
