no-type-in-docs

Remove redundant type information from comments in TypeScript documentation.

Updated Jul 17, 2017
One-click install
npx skills add https://github.com/luyi985/lyi-bash --skill no-type-in-docs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: no-type-in-docs
Source: https://github.com/luyi985/lyi-bash/tree/main/ai/skills/no-type-in-docs
Command: npx skills add https://github.com/luyi985/lyi-bash --skill no-type-in-docs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Comments describing types drift out of sync with code. TypeScript's type system is designed to be compact and readable - use it as your primary source of type documentation.

Core Features & Use Cases

  • Enforces that type information is not repeated in comments and documentation.
  • Guides developers to write comments that explain intent, rationale, and behavior rather than types.
  • Applicable to TypeScript and other typed languages when documenting functions, parameters, and return values in both frontend and backend codebases.

Quick Start

Refactor a sample function to remove type details from comments and ensure the function's behavior is explained without duplicating types.

Frequently Asked Questions about no-type-in-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I avoid duplicating TypeScript type information in comments?

Yes, you should remove type details from inline documentation for TypeScript functions. Prioritize explaining the function's behavior and rationale instead of repeating parameter and return value types.

Why do comments describing types drift out of sync with code?

Comments describing types drift out of sync with code because types are duplicated in documentation. TypeScript's compact type system should be the primary source of type documentation to prevent this drift.

How do I document readonly parameters in TypeScript functions?

To document readonly parameters in TypeScript functions, use readonly modifiers for non-mutation semantics and let the type annotation speak for itself, focusing the comment on the parameter's purpose.

What's the best way to write intent-focused comments for typed languages?

The best way to write intent-focused comments for typed languages is to eliminate redundant type information and explain the why and how of the code, ensuring frontend and backend projects remain maintainable.

Can I use this documentation principle for both frontend and backend TypeScript projects?

Yes, you can apply this documentation principle to both frontend and backend TypeScript projects. It enforces not duplicating types in comments across all functions, parameters, and return values.