Ts docs

.agents/skills/tsdoc-jsdoc-authoring/AGENTS.md

@@ -0,0 +1,228 @@
+# TSDoc and JSDoc Best Practices
+
+**Version 1.0.0**  
+Custom Authoring Guide  
+February 2026
+
+> **Note:**  
+> This document is designed for agents and LLMs writing or reviewing TypeScript
+> and JavaScript documentation comments using TSDoc and JSDoc. It mirrors a
+> rule-driven format where each rule has clear "use" and "avoid" guidance with
+> incorrect and correct examples.
+
+---
+
+## Abstract
+
+Comprehensive TSDoc and JSDoc authoring guide for automated documentation generation and review. Contains focused rules across core contract tags, linking/reuse tags, package/internal docs, policy tags, and JavaScript-focused docstring patterns. Each rule explains when to use the tag, when not to use it, and includes concrete incorrect/correct examples.
+
+## Read Order (Context-Safe)
+
+Before using this catalog, route through one focused index:
+
+- `indexes/tsdoc-index.md`
+- `indexes/jsdoc-authoring-index.md`
+- `indexes/jsdoc-consistency-index.md`
+
+This file is a reference catalog. Load only the relevant subsection after choosing an index.
+
+---
+
+## Rule Index
+
+### 1. Core API Contract Rules
+
+1.1 [Write Clear Summary Sentences](#11-write-clear-summary-sentences)  
+1.2 [Use `@remarks` for Long-Form Context](#12-use-remarks-for-long-form-context)  
+1.3 [Document Parameters with `@param`](#13-document-parameters-with-param)  
+1.4 [Document Generics with `@typeParam`](#14-document-generics-with-typeparam)  
+1.5 [Document Return Semantics with `@returns`](#15-document-return-semantics-with-returns)  
+1.6 [Document Expected Failures with `@throws`](#16-document-expected-failures-with-throws)  
+1.7 [Use `@example` for Non-Obvious Usage](#17-use-example-for-non-obvious-usage)  
+1.8 [Use `@deprecated` with Migration Guidance](#18-use-deprecated-with-migration-guidance)
+
+### 2. Cross-Reference and Reuse Rules
+
+2.1 [Prefer `{@link ...}` for Symbol References](#21-prefer-link--for-symbol-references)  
+2.2 [Use `@see` for Related APIs](#22-use-see-for-related-apis)  
+2.3 [Use `@inheritDoc` Only for Equivalent Contracts](#23-use-inheritdoc-only-for-equivalent-contracts)  
+2.4 [Use `{@label ...}` Only for Structured References](#24-use-label--only-for-structured-references)
+
+### 3. Package and Internal Notes
+
+3.1 [Use `@packageDocumentation` for Entrypoint Docs](#31-use-packagedocumentation-for-entrypoint-docs)  
+3.2 [Use `@privateRemarks` for Maintainer-Only Notes](#32-use-privateremarks-for-maintainer-only-notes)  
+3.3 [Document Defaults with `@defaultValue`](#33-document-defaults-with-defaultvalue)
+
+### 4. Stability and Modifier Policy
+
+4.1 [Apply Release Tags Consistently](#41-apply-release-tags-consistently)  
+4.2 [Use Modifier Tags Only When Semantically True](#42-use-modifier-tags-only-when-semantically-true)  
+4.3 [Do Not Mix JSDoc Type Syntax into TSDoc](#43-do-not-mix-jsdoc-type-syntax-into-tsdoc)
+
+### 5. JSDoc Rules (JavaScript)
+
+5.1 [Write JSDoc Summaries with Intent](#51-write-jsdoc-summaries-with-intent)  
+5.2 [Document Parameters with JSDoc Type Expressions](#52-document-parameters-with-jsdoc-type-expressions)  
+5.3 [Use Optional and Default Parameter Strings Correctly](#53-use-optional-and-default-parameter-strings-correctly)  
+5.4 [Use Nested Property Namepaths for Object Inputs](#54-use-nested-property-namepaths-for-object-inputs)  
+5.5 [Document Return Value Semantics with `@returns`](#55-document-return-value-semantics-with-returns)  
+5.6 [Document Error Contracts with `@throws`](#56-document-error-contracts-with-throws)  
+5.7 [Add Practical `@example` Snippets](#57-add-practical-example-snippets)  
+5.8 [Define Reusable Shapes with `@typedef` and `@property`](#58-define-reusable-shapes-with-typedef-and-property)  
+5.9 [Document Async Behavior with `@async`](#59-document-async-behavior-with-async)  
+5.10 [Document Generator Output with `@yields`](#510-document-generator-output-with-yields)  
+5.11 [Document Constructors and Classes Clearly](#511-document-constructors-and-classes-clearly)  
+5.12 [Use `@module` for Module-Level Docs](#512-use-module-for-module-level-docs)  
+5.13 [Validate Access Tags with `check-access`](#513-validate-access-tags-with-check-access)  
+5.14 [Restrict `@implements` to Classes or Constructors](#514-restrict-implements-to-classes-or-constructors)
+
+---
+
+## 1. Core API Contract Rules
+
+### 1.1 Write Clear Summary Sentences
+
+See: `rules/tsdoc/core/tsdoc-summary.md`
+
+### 1.2 Use `@remarks` for Long-Form Context
+
+See: `rules/tsdoc/core/tsdoc-remarks.md`
+
+### 1.3 Document Parameters with `@param`
+
+See: `rules/tsdoc/core/tsdoc-param.md`
+
+### 1.4 Document Generics with `@typeParam`
+
+See: `rules/tsdoc/core/tsdoc-typeparam.md`
+
+### 1.5 Document Return Semantics with `@returns`
+
+See: `rules/tsdoc/core/tsdoc-returns.md`
+
+### 1.6 Document Expected Failures with `@throws`
+
+See: `rules/tsdoc/core/tsdoc-throws.md`
+
+### 1.7 Use `@example` for Non-Obvious Usage
+
+See: `rules/tsdoc/core/tsdoc-example.md`
+
+### 1.8 Use `@deprecated` with Migration Guidance
+
+See: `rules/tsdoc/core/tsdoc-deprecated.md`
+
+## 2. Cross-Reference and Reuse Rules
+
+### 2.1 Prefer `{@link ...}` for Symbol References
+
+See: `rules/tsdoc/crossref/tsdoc-link.md`
+
+### 2.2 Use `@see` for Related APIs
+
+See: `rules/tsdoc/crossref/tsdoc-see.md`
+
+### 2.3 Use `@inheritDoc` Only for Equivalent Contracts
+
+See: `rules/tsdoc/crossref/tsdoc-inheritdoc.md`
+
+### 2.4 Use `{@label ...}` Only for Structured References
+
+See: `rules/tsdoc/crossref/tsdoc-label.md`
+
+## 3. Package and Internal Notes
+
+### 3.1 Use `@packageDocumentation` for Entrypoint Docs
+
+See: `rules/tsdoc/policy/tsdoc-package-documentation.md`
+
+### 3.2 Use `@privateRemarks` for Maintainer-Only Notes
+
+See: `rules/tsdoc/policy/tsdoc-private-remarks.md`
+
+### 3.3 Document Defaults with `@defaultValue`
+
+See: `rules/tsdoc/policy/tsdoc-default-value.md`
+
+## 4. Stability and Modifier Policy
+
+### 4.1 Apply Release Tags Consistently
+
+See: `rules/tsdoc/policy/tsdoc-release-tags.md`
+
+### 4.2 Use Modifier Tags Only When Semantically True
+
+See: `rules/tsdoc/policy/tsdoc-modifier-tags.md`
+
+### 4.3 Do Not Mix JSDoc Type Syntax into TSDoc
+
+See: `rules/tsdoc/policy/tsdoc-no-jsdoc-braces.md`
+
+## 5. JSDoc Rules (JavaScript)
+
+These rules are part of the default documentation standard and should be followed even without an active linter.
+
+### 5.1 Write JSDoc Summaries with Intent
+
+See: `rules/jsdoc/core/jsdoc-summary.md`
+
+### 5.2 Document Parameters with JSDoc Type Expressions
+
+See: `rules/jsdoc/core/jsdoc-param.md`
+
+### 5.3 Use Optional and Default Parameter Strings Correctly
+
+See: `rules/jsdoc/core/jsdoc-optional-default.md`
+
+### 5.4 Use Nested Property Namepaths for Object Inputs
+
+See: `rules/jsdoc/core/jsdoc-property-namepaths.md`
+
+### 5.5 Document Return Value Semantics with `@returns`
+
+See: `rules/jsdoc/core/jsdoc-returns.md`
+
+### 5.6 Document Error Contracts with `@throws`
+
+See: `rules/jsdoc/core/jsdoc-throws.md`
+
+### 5.7 Add Practical `@example` Snippets
+
+See: `rules/jsdoc/core/jsdoc-example.md`
+
+### 5.8 Define Reusable Shapes with `@typedef` and `@property`
+
+See: `rules/jsdoc/advanced/jsdoc-typedef-property.md`
+
+### 5.9 Document Async Behavior with `@async`
+
+See: `rules/jsdoc/advanced/jsdoc-async.md`
+
+### 5.10 Document Generator Output with `@yields`
+
+See: `rules/jsdoc/advanced/jsdoc-yields.md`
+
+### 5.11 Document Constructors and Classes Clearly
+
+See: `rules/jsdoc/advanced/jsdoc-class-constructor.md`
+
+### 5.12 Use `@module` for Module-Level Docs
+
+See: `rules/jsdoc/advanced/jsdoc-module.md`
+
+### 5.13 Validate Access Tags with `check-access`
+
+See: `rules/jsdoc/core/jsdoc-check-access.md`
+
+### 5.14 Restrict `@implements` to Classes or Constructors
+
+See: `rules/jsdoc/advanced/jsdoc-implements-on-classes.md`
+
+---
+
+## References
+
+1. [https://tsdoc.org](https://tsdoc.org)
+2. [https://github.com/microsoft/tsdoc](https://github.com/microsoft/tsdoc)
+3. [https://jsdoc.app](https://jsdoc.app)

.agents/skills/tsdoc-jsdoc-authoring/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: tsdoc-jsdoc-authoring
+description: Write and review API documentation comments using TSDoc and JSDoc best practices. Use when the user asks for docs, doc comments, TSDoc, JSDoc, @param/@returns help, or documentation quality improvements in JavaScript or TypeScript code.
+metadata:
+  author: custom
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# TSDoc and JSDoc Authoring
+
+Create high-quality documentation comments for functions, classes, interfaces, types, modules, and exported APIs.
+
+## When to Apply
+
+Use this skill when the user asks to:
+
+- add or improve code comments/docs
+- write TSDoc or JSDoc
+- document params, return values, thrown errors, or examples
+- standardize documentation style across files
+
+## Routing (Read This First)
+
+Choose one focused index before loading rule files:
+
+- TypeScript APIs and typed exports: `indexes/tsdoc-index.md`
+- JavaScript authoring and shape docs: `indexes/jsdoc-authoring-index.md`
+- Strict consistency/lint-safe output standards: `indexes/jsdoc-consistency-index.md`
+
+## Rule 1: Choose the Correct Standard
+
+- Use **TSDoc** for TypeScript code and typed public APIs.
+- Use **JSDoc** for JavaScript code or projects using JSDoc tooling.
+- Do not mix tag syntaxes from both standards in one comment block.
+
+## Workflow
+
+1. Read the target file and identify the symbol's purpose and side effects.
+2. Prefer documenting exported/public APIs first.
+3. Write a one-line summary in plain language.
+4. Add only meaningful tags (no empty or redundant tags).
+5. Validate tag names and formatting against the relevant standard.
+6. Ensure comments match actual behavior (inputs, outputs, errors, async behavior).
+
+## Authoring Rules (Both Standards)
+
+- Describe intent and behavior, not obvious implementation details.
+- Keep summaries concise and action-oriented ("Returns...", "Creates...", "Parses...").
+- Document every parameter and explain what each parameter does.
+- If a parameter is an object, document each object property and what it does.
+- Use imperative, consistent phrasing for `@param` descriptions.
+- Document thrown errors with `@throws` when behavior depends on error handling.
+- Add `@example` only when it clarifies non-obvious usage.
+- Do not restate TypeScript types in prose unless it adds semantic meaning.
+
+## TSDoc Rules
+
+Use these tags by default when relevant:
+
+- `@param` for each function argument
+- `@typeParam` for generic parameters
+- `@returns` for return semantics
+- `@remarks` for longer contextual details
+- `@throws` for exceptional behavior
+- `@example` for practical usage
+- `@deprecated` for migration guidance
+
+TSDoc formatting reminders:
+
+- Use `@param name - Description` with a hyphen separator.
+- Prefer inline links with `{@link SymbolName}`.
+- Keep release tags (`@alpha`, `@beta`, `@public`, `@internal`) aligned with project policy.
+- For object parameters in TypeScript, prefer a named `type` or `interface` and add `/** ... */` comments on each property so VS Code hovers/autocomplete show per-property docs.
+
+## JSDoc Rules
+
+Use these tags by default when relevant:
+
+- `@param {Type} name` (with optional/default forms when needed)
+- `@returns {Type}` (or `@return`)
+- `@throws {Type}` when known
+- `@typedef` and `@property` for reusable object shapes
+- `@example` for usage snippets
+- `@async` and `@yields` for async/generator behavior when needed
+
+JSDoc formatting reminders:
+
+- Optional params: `@param {string} [name]`
+- Optional with default: `@param {string} [name=John Doe]`
+- Nested object props: `@param {Object} options` and `@param {string} options.mode`
+
+## JSDoc Consistency Standard
+
+Apply these rules by default in all JavaScript documentation, regardless of lint setup.
+
+- Keep `@access` usage consistent per block (`@access <level>` or one shorthand access tag).
+- Use `@implements` only on classes/constructors.
+- Prefer rule-specific guidance from the `rules/jsdoc/**` files when there is a conflict.
+
+## Output Expectations
+
+When updating comments:
+
+- keep existing project conventions unless user requests a migration
+- preserve behavior accuracy over verbosity
+- avoid adding comments to private/internal symbols unless requested
+
+## Additional Reference
+
+For templates and tag cheat sheets, see [reference.md](reference.md).
+
+## Rule Files
+
+Use focused indexes to avoid loading unrelated rules:
+
+- TSDoc index: `indexes/tsdoc-index.md`
+- JSDoc authoring index: `indexes/jsdoc-authoring-index.md`
+- JSDoc consistency index: `indexes/jsdoc-consistency-index.md`
+
+## Full Compiled Document
+
+For the full rule index and category guide: `AGENTS.md`

.agents/skills/tsdoc-jsdoc-authoring/indexes/jsdoc-authoring-index.md

@@ -0,0 +1,30 @@
+---
+title: JSDoc Authoring Index
+scope: JavaScript documentation patterns
+---
+
+# JSDoc Authoring Index
+
+Use this index for normal JavaScript doc authoring tasks. For strict consistency rules, use `indexes/jsdoc-consistency-index.md`.
+
+## Core Authoring
+
+- `rules/jsdoc/core/jsdoc-summary.md`
+- `rules/jsdoc/core/jsdoc-param.md`
+- `rules/jsdoc/core/jsdoc-optional-default.md`
+- `rules/jsdoc/core/jsdoc-property-namepaths.md`
+- `rules/jsdoc/core/jsdoc-returns.md`
+- `rules/jsdoc/core/jsdoc-throws.md`
+- `rules/jsdoc/core/jsdoc-example.md`
+
+## Advanced Authoring
+
+- `rules/jsdoc/advanced/jsdoc-typedef-property.md`
+- `rules/jsdoc/advanced/jsdoc-async.md`
+- `rules/jsdoc/advanced/jsdoc-yields.md`
+- `rules/jsdoc/advanced/jsdoc-class-constructor.md`
+- `rules/jsdoc/advanced/jsdoc-module.md`
+
+## Deep Reference
+
+- `reference.md` (templates and syntax cheatsheets)