repo-source-code-document_skill

Overview

This skill documents Valibot TypeScript source code in /library/src/ by generating JSDoc comments and inline comments that follow the library's conventions. It focuses on schemas, actions, methods, and utilities to produce consistent, parseable, and tree-shake friendly documentation. Use it to enforce terminology, purity annotations, overload patterns, and inline comment styles across the codebase.

How this skill works

The skill inspects TypeScript AST and source text to locate interfaces, function overloads, implementation blocks, and internal utilities under /library/src/. It emits JSDoc comments following strict first-line patterns, param/returns formats, @internal usage for utilities, and inserts // @__NO_SIDE_EFFECTS__ for pure factory functions. It also rewrites or adds inline comments using present-tense verbs, omitting articles except in Hint comments.

When to use it

• When adding or updating schema factories (string, object, array, etc.)
• When documenting validation or transformation actions (email, minLength, parse)
• When writing or refactoring methods with complex logic (pipe, parse)
• When creating or updating internal utilities (_addIssue, _stringify)
• When enforcing terminology and JSDoc consistency across the library

Best practices

• Follow first-line patterns exactly: interfaces use "[Name] [category] interface." and functions use "Creates a [name] [category]."
• Give each function overload a complete JSDoc block with blank lines between description, params, and returns
• Only add // @__NO_SIDE_EFFECTS__ to pure functions; omit for mutating functions like _addIssue
• Prefix internal utilities with _ and mark them @internal in JSDoc
• Write inline comments that describe WHAT the next block does using present-tense verbs and omit articles, except in Hint comments

Example use cases

• Document new schema file: add issue interface JSDoc, schema interface JSDoc, overload JSDoc blocks, implementation without JSDoc and with // @__NO_SIDE_EFFECTS__ if pure
• Annotate action files: create issue and action interfaces with JSDoc and implement pure factories with the purity marker
• Refactor method file: add descriptive inline comments for each section header and conditional branch using present-tense, article-free phrasing
• Add an internal utility: prefix with _, add @internal JSDoc, and add // @__NO_SIDE_EFFECTS__ only if function is pure