One Typo, Two Years: Fixing a JSDoc Grammar Error in TypeScript

A one-character grammar error in TypeScript’s es2015.symbol.d.ts has been silently making JSDoc less readable for every TypeScript developer with editor intellisense. The @returns tag on SymbolConstructor.keyFor read “returns a undefined” — an article mismatch before the vowel-sound word “undefined.”

Repo: microsoft/TypeScript PR: #63525 Status: PR-submitted Fix scope: 1 line changed in src/lib/es2015.symbol.d.ts

The Bug

The keyFor method on SymbolConstructor converts a registered symbol back to its string key:

interface SymbolConstructor {
    /**
     * Returns a key from the global symbol registry matching the given Symbol if found.
     * Otherwise, returns a undefined.
     * @param sym Symbol to find the key for.
     */
    keyFor(sym: symbol): string | undefined;
}

The line * Otherwise, returns a undefined. is grammatically incorrect. The indefinite article “a” is used before consonant sounds; “undefined” begins with a vowel sound, making the correct form “returns undefined” (no article) or “returns undefined” (referencing the literal value).

The Fix

A single substitution in src/lib/es2015.symbol.d.ts:

- * Otherwise, returns a undefined.
+ * Otherwise, returns undefined.

Why Grammar in JSDoc Matters

TypeScript’s lib.d.ts files are the most-read type definitions in the JavaScript ecosystem — millions of developers see them daily through IDE intellisense panels. Each JSDoc comment is a touchpoint for API understanding. Grammar errors in these definitions erode the professional polish of a project that standardizes JavaScript development.

While a single article mismatch is minor, the cumulative effect of many small inaccuracies adds friction. Maintainers at Microsoft have accepted this class of fix before — our prior PR #63491 (a JSDoc typo in es2015.collection.d.ts) was merged in May 2026 — confirming that lib.d.ts JSDoc fixes are well within the accepted contribution categories for a repository in feature-freeze for the Go-based rewrite.

Pattern: Finding JSDoc Grammar Issues

Automated check

# Check JSDoc @returns tags for article-vowel mismatches
grep -r 'returns a [aeiouh]' src/*.d.ts \
  | grep -v '@returns a new\|@returns a Promise\|@returns a string\|@returns a number'

This filters for article-vowel mismatches while skipping correct usages like “returns a Promise” or “returns a new instance.”

What to look for manually

When reviewing type definition files, watch for these common JSDoc grammar patterns:

Pattern	Wrong	Correct
Article before vowel sound	”a undefined"	"undefined” (or “an undefined”)
Missing article	”returns reference"	"returns a reference”
Wrong article	”a HTTP error"	"an HTTP error”

Contribution workflow for type-definition fixes

Fork and clone microsoft/TypeScript
Find the issue in src/lib/*.d.ts
Make the fix, run the test suite: npx hereby tests
Submit PR with lib label

TypeScript’s lib.d.ts files accept JSDoc fixes even during feature-freeze because they don’t affect compiler behavior — only developer experience.