Drop in a
JavaScript file.
Ship an API reference.
A dependency-free parser that reads declarations, arrow functions, classes and object members, then merges @jsdoc tags, TypeScript annotations and inferred types into one GitHub-flavoured reference — with a lint pass that tells you what you forgot to document.
pipeline
- scan mask strings, comments, regex literals
- parse function · arrow · class · member
- resolve jsdoc ⊕ ts types ⊕ inference
- emit markdown + usage examples + lint
How to use it
Four moves, start to finish. Every step has a button that loads a real snippet so you can watch the output change.
Paste, drop or browse
Drop any .js / .mjs / .ts file onto the editor, or pick one from disk. The parser handles function declarations, arrow and function expressions, class members (including getters, setters, statics and generators), object-literal members and export forms.
Let it resolve the types
Types are resolved in priority order: @param {T} / @returns {T} tags first, then TypeScript annotations such as (size: number = 2), then inference from defaults and return expressions. Every type is labelled with where it came from, so you never mistake a guess for a fact.
| Name | Type | Source | Attributes |
| ---- | ---- | ------ | ---------- |
| `shape` | `Circle \| Rect` | jsdoc | required |
| `size` | `number` | inferred from default `2` | default `2` |
| `deep` | `boolean` | inferred from default `false` | default `false` |Switch to the lint tab
The lint pass is what eslint-plugin-jsdoc would complain about: missing blocks, untyped parameters, summaries that aren't imperative sentences, undocumented @returns and @throws, plus “more than four parameters — use an options object”. The score is weighted: description 40, parameter types 20, parameter prose 15, returns 15, example 10.
slugify(text)
error no JSDoc block found — add a summary, @param and @returns
warn parameter `text` has no type
warn return value is undocumented (inferred: string)
hint no @example — one runnable snippet beats three paragraphsCopy or download
Copy the markdown straight into a PR body, or download <title>.md and commit it next to the source. The output is plain GitHub-flavoured markdown — tables, fenced js blocks, anchor links — so it renders identically on GitHub, in VitePress, or inside a README.
## `apiClient.get(path, query)`
Fetch a JSON resource.
**Kind** `async method` · **In** `ApiClient` · **Source** `api-client.js:41`
### Returns
**`Promise<Object>`** — The parsed response body.
### Throws
- **`ApiError`** — If the request fails or the API returns 4xx/5xx.Field notes: what good API docs do
Distilled from MDN's reference grammar, the JSDoc/TSDoc tag specs, the NumPy docstring standard and the READMEs below. The generator's output shape follows these rules on purpose.
optional, defaults, rest args and nullability explicitly — MDN's parameter tables do exactly this and it's why they're skimmable.Promise.… hand-waving. Lodash and Chalk built entire reputations on copy-pasteable snippets.@throws with the exact error class and the condition that triggers it. Silent error paths are the #1 support cost in OSS.eslint-plugin-jsdoc, jsdoc -X, remark-lint) and fail the build on regressions. A coverage score you can watch go up is worth ten style guides.@deprecated with the replacement and the removal version, every time. Never let a signature change silently.Repos worth stealing from
Open-source projects whose documentation is a reference implementation of the rules above — and the one habit to copy from each.
| Project | Where the docs live | Steal this |
|---|---|---|
| lodash/lodash | JSDoc per method, docs/ generated | Every method carries an @since, a category, and a dozen example lines showing input → output. The example is the spec. Also: consistent @param {Array} array phrasing across 300+ functions. |
| ramda/ramda | JSDoc + transpiled type sigs | Pseudo-type signatures (R.curry(f, n, …)) that communicate currying better than prose ever could. Type-first, then one terse example. |
| reduxjs/redux | JSDoc on public API + separate guides | Reference docs state the contract; the guide explains the concept. Never mix the two in one file. createStore's docblock is a model of param-by-param clarity. |
| expressjs/express | Guide site with per-method pages | Signature line first (app.METHOD(path, callback)), then a minimal runnable snippet per variant. HTTP semantics documented as a table of statuses. |
| vuejs/core | .d.ts + VitePress API reference | Uniform “Type:” / “Detailed:” blocks and option tables with defaults inline. Types are the source of truth; prose only adds what types can't say. |
| colinhacks/zod | Inline JSDoc that powers autocomplete | Doc comments written for the editor tooltip, not just the website — one summary line + a link to the deep docs. Docs that earn their keep inside the IDE. |
| mrdoob/three.js | docs/api/ + editable live examples | Every reference page has a live example you can change and run. Docs as a test fixture, not a screenshot. |
| d3/d3 | README-as-reference, Observable notebooks | Docs embedded in the repo README with a rendered example beside each function. Zero friction between reading and trying. |
| microsoft/tsdoc | A spec for doc comments | Define the tag vocabulary before writing docs. TSDoc exists because teams kept inventing incompatible tags — pick a grammar and enforce it. |
| numpy/numpy python | Docstring convention doc | The section grammar this tool copies: Summary · Parameters · Returns · Raises · See Also · Examples. Language-agnostic best structure, full stop. |
| octokit/octokit.js | Generated from the OpenAPI spec | When a machine-readable spec exists, generate the docs from it — never hand-write what a generator can emit. |
| chalk/chalk | README | “Results” blocks: the snippet and its rendered output stacked. Cheap to write, extremely fast to read. |