Skip to content
Skills Library
Programming · Writing

typescript-advanced-docs

/typescript-advanced-docs

Documentation tooling for TypeScript projects — JSDoc comment patterns that surface in IDE tooltips, TypeDoc configuration for generating API documentation sites, Architectural Decision Record (ADR) templates for recording design decisions, and framework-specific documentation patterns (NestJS, React, Angular/Compodoc). Use when writing JSDoc for a public API, setting up TypeDoc to generate documentation from source, recording why a technical decision was made, or documenting a framework-specific pattern.

Repository
tekhne ↗
Licence
MIT
Last repository change
21.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
19
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Documentation tooling for TypeScript projects — JSDoc comment patterns that surface in IDE tooltips, TypeDoc configuration for generating API documentation sites, Architectural Decision Record (ADR) templates for recording design decisions, and framework-specific documentation patterns (NestJS, React, Angular/Compodoc). Use when writing JSDoc for a public API, setting up TypeDoc to generate documentation from source, recording why a technical decision was made, or documenting a framework-specific pattern.

Original author description

Documentation tooling for TypeScript projects — JSDoc comment patterns that surface in IDE tooltips, TypeDoc configuration for generating API documentation sites, Architectural Decision Record (ADR) templates for recording design decisions, and framework-specific documentation patterns (NestJS, React, Angular/Compodoc). Use when writing JSDoc for a public API, setting up TypeDoc to generate documentation from source, recording why a technical decision was made, or documenting a framework-specific pattern.

How it works

  1. Mindset
  2. When to Apply
  3. Use When
  4. Scope
  5. When NOT to Use
  6. Quick Commands
  7. Anti-Patterns
  8. References
Original SKILL.md headings · 108 lines, 704 words
SKILL.md preview
---
name: typescript-advanced-docs
description: Documentation tooling for TypeScript projects — JSDoc comment patterns that surface in IDE tooltips, TypeDoc configuration for generating API documentation sites, Architectural Decision Record (ADR) templates for recording design decisions, and framework-specific documentation patterns (NestJS, React, Angular/Compodoc). Use when writing JSDoc for a public API, setting up TypeDoc to generate documentation from source, recording why a technical decision was made, or documenting a framework-specific pattern.
allowed-tools: Read, Write, Edit, Bash
---

# TypeScript Documentation

Documentation tooling and conventions for TypeScript codebases: JSDoc, TypeDoc, ADRs, and framework-specific patterns.

## Mindset

Write documentation that a compiler-checked type can't already express — a JSDoc `@param` restating a parameter's type the signature already shows is noise; a JSDoc comment explaining *why* a parameter exists, what invariant it must satisfy, or what happens at its edge cases earns its place. Treat an ADR as a record for a future reader who wasn't in the room, not a justification written for the reviewer who is: state the decision, the alternatives considered, and the consequences accepted, in that order. Generated documentation (TypeDoc output) is only as good as the JSDoc it's generated from — investing in TypeDoc configuration without investing in the comments it reads from produces a well-formatted site with nothing useful in it.

## When to Apply

Use this skill when:

- Writing JSDoc comments for a public API surface
- Configuring TypeDoc to generate a documentation site from TypeScript source
- Recording an architectural decision with an ADR
- Documenting a framework-specific pattern (NestJS decorators, React components, Angular/Compodoc)

## Use When

- "How should I document this public function/class with JSDoc?"
- "How do I set up TypeDoc to generate our API docs?"
- "How do I write an ADR for this decision?"
- "What's the convention for documenting a NestJS/React/Angular component?"

## Scope

### In Scope

- JSDoc comment patterns and best practices.
- TypeDoc configuration and setup.
- ADR templates and structure.
- Framework-specific documentation patterns (NestJS, React, Angular).

### Out of Scope

- The type-first design decisions an ADR might record — see the sibling `typescript-practices` skill for the workflow itself.
- Generating documentation content from types mechanically covered elsewhere (e.g. what a mapped type does) — see the sibling `typescript-type-system` skill for the mechanics; this skill covers how to document the result.

## When NOT to Use

Do not use this skill for deciding *what* a type or pattern should do — it covers documenting a decision or API, not making one. Do not use it as a substitute for actually running `npx typedoc` and checking the generated output — a JSDoc comment that looks right can still render incorrectly (a malformed `@example` block, a broken `{@link}`).

## Quick Commands

### Generate Docs

```bash
npx typedoc --out docs src/index.ts
```

## Anti-Patterns

### NEVER write a JSDoc comment that only restates the type signature

**WHY:** a comment that duplicates what the signature already says adds reading overhead with no new information, and drifts out of sync with the signature over time.

**BAD**:

```typescript
/**
 * @param name - a string
 * @returns a string
 */
function greet(name: string): string { return `Hello, ${name}`; }
```

**GOOD**:

```typescript
/**
 * Formats a greeting for display. Falls back to "Guest" if `name` is empty,
 * since an empty greeting would render as blank in the header component.
 */
function greet(name: string): string {
  return `Hello, ${name || "Guest"}`;
}
```

### NEVER write an ADR that only justifies a decision already made

**WHY:** an ADR's value is to a future reader deciding whether the reasoning still holds; a one-sided justification omits the alternatives and trade-offs that reader needs to judge that.

**BAD**: "We chose Zod because it's good." (no alternatives, no consequences, no context)

**GOOD**: A record with Context (what problem existed), Decision (what was chosen), Alternatives Considered (what else, and why not), and Consequences (what this commits the codebase to).

### NEVER configure TypeDoc without first ensuring the source has real JSDoc to generate from

**WHY:** TypeDoc renders whatever comments exist; a well-configured generator over undocumented source produces a polished site of empty pages.

**BAD**: Running `npx typedoc --out docs src/index.ts` as the first and only documentation step on undocumented code.

**GOOD**: Add JSDoc to the public API surface first, then configure and run TypeDoc to publish it.

## References

| File | Covers |
| --- | --- |
| `references/jsdoc-patterns.md` | JSDoc comment best practices and patterns |
| `references/typedoc-config.md` | TypeDoc configuration and setup |
| `references/adr-templates.md` | Architectural Decision Record templates |
| `references/framework-docs.md` | Framework-specific documentation patterns (NestJS, React, Angular/Compodoc) |

- [TSDoc Specification](https://tsdoc.org/)
- [TypeDoc Documentation](https://typedoc.org/)
- [ADR GitHub Organization](https://adr.github.io/)
Files in this package (19)
  • SKILL.md 5 KB
  • .audits/2026-09-23/Analysis.md 1 KB
  • .audits/2026-09-23/Remediation.md 2 KB
  • .audits/2026-09-23/audit.json 1 KB
  • evals/instructions.json 2 KB
  • evals/summary.json 1 KB
  • evals/scenario-0/capability.txt 1 KB
  • evals/scenario-0/criteria.json 1 KB
  • evals/scenario-0/task.md 1 KB
  • evals/scenario-1/capability.txt 1 KB
  • evals/scenario-1/criteria.json 1 KB
  • evals/scenario-1/task.md 1 KB
  • evals/scenario-2/capability.txt 1 KB
  • evals/scenario-2/criteria.json 1 KB
  • evals/scenario-2/task.md 1 KB
  • references/adr-templates.md 7 KB
  • references/framework-docs.md 7 KB
  • references/jsdoc-patterns.md 8 KB
  • references/typedoc-config.md 6 KB

Versions

The database has no other skills named typescript-advanced-docs.

Database snapshot: 13.11.2026 · package version cae46fb5b154 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100typescript-docs
    Generates comprehensive TypeScript documentation using JSDoc, TypeDoc, and multi-layered documentation patterns for different audiences. Use when creating API documentation, architectural decision records (ADRs), code examples, and framework-specific patterns for NestJS,…
  • 100jsdoc
    Write, fix, or review JSDoc documentation for JavaScript and TypeScript code. Detects whether the project uses typed JSDoc (plain JS with checkJs), TypeScript (docs without type duplication), or a doc generator (TypeDoc, JSDoc CLI), and documents accordingly. Use when adding…
  • 100jsdoc-tsdoc
    JSDoc and TSDoc documentation standards. Covers syntax, tags, TypeScript integration, documentation generation, and API documentation best practices. USE WHEN: user mentions "TSDoc", "TypeScript documentation", "API documentation", asks about "documenting TypeScript", "@param",…
  • 100jsdoc
    JSDoc - documentation generator for JavaScript with type annotations. USE WHEN: user mentions "JSDoc", "JavaScript documentation", asks about "documenting JavaScript", "type hints", "jsdoc comments", "API documentation generation" DO NOT USE FOR: TypeScript - use `jsdoc-tsdoc`…
  • 95documentation
    Update toolkit documentation, navigation, and shared site components. Use for user guides, MCP pages, CLI reference, VitePress styling, and JSDoc for TypeDoc generation.
  • 100jsdoc-comment-generator
    Generate jsdoc comment generator operations. Auto-activating skill for Technical Documentation. Triggers on: jsdoc comment generator, jsdoc comment generator Part of the Technical Documentation skill category. Use when working with jsdoc comment generator functionality. Trigger…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.