docstring-generator

Files (1)

• SKILL.md

SKILL.md (first lines)

# Docstring Generator

Generates or updates doc comments for TypeScript and Rust source files. The
skill analyzes the public API surface (functions, methods, classes/structs,
traits/interfaces, enums) and produces language-idiomatic documentation.

## Inputs

| Input | Type | Required | Description |
|---|---|---|---|
| `language` | string | yes | `"typescript"` or `"rust"` |
| `file_path` | string | yes | Path of the file being edited |
| `full_text` | string | yes | Entire contents of the file |
| `selection_range` | object | no | `{ start_line, end_line }` (1-based, inclusive) |
| `mode` | string | no | `"update_missing"` (default) or `"update_all"` |
| `public_only` | boolean | no | If true (default), only document exported/public items |

## Workflow

### Step 1: Parse declarations

Mentally parse `full_text` to find all declarations relevant to the language,
`public_only`, and `selection_range` settings.

**TypeScript declarations to document:**
- Exported functions, async functions, and generators
- Exported classes and their public/protected methods
- Exported interfaces and type aliases
- Exported enums
- Exported const/let/var at module level (when they hold complex types)

**Rust declarations to document:**
- `pub fn` (free functions and methods)
- `pub struct` and its `pub` fields
- `pub enum` and its variants
- `pub trait` and its method signatures
- `pub type` and `pub const` items
- `pub mod` (public modules)

### Step 2: Generate doc comments

For each target declaration, follow the language-specific rules below.

### Step 3: Merge into file

Insert or update the doc comment immediately before the declaration, preserving
all existing formatting, indentation, and code. Return the full `updated_text`
with only doc comment lines changed.

## Behavior & Style Rules

### General Rules (all languages)

- **Preserve everything**: Do not change code semantics, identifiers,
  formatting, or indentation. Only touch doc comment lines.
- **No speculation**: If unsure about behavior, write neutral high-level
  descriptions instead of guessing.
- **Present tense, concise**: Describe what the item *does*, not what it *is*.
  Avoid restating obvious type information unless it aids clarity.
- **Idempotent**: Running the skill twice on the same file should produce the
  same result.
- **Respect developer notes**: In `update_all` mode, preserve explicit warnings,
  safety notes, panic documentation, and custom annotations.

### TypeScript Rules

**Comment style**: Use `/** ... */` TSDoc/JSDoc block comments immediately
before the declaration.

**Functions & methods:**
- First line: one-sentence summary of what the function does.
- Then `@param name - description` for each parameter.
- Then `@returns` with a short description if the function returns non-void.

**Classes, interfaces, type aliases, enums:**
- Summarize the purpose and role of the type.
- Prefer describing intent over implementation details.

**Mode behavior:**
- `update_missing`: Do not rewrite existing comments unless they are obviously
  placeholder (e.g., `TODO`, `fix`, `FIXME`, `@todo`).
- `update_all`: Improve unclear comments but preserve any explicit developer
  notes or warnings.

**Example:**
```typescript
/** Loads a user by id from the primary data store.
 * @param id - Unique identifier of the user.
 * @returns The user if found, otherwise null.
 */
async function getUserById(id: string): Promise<User | null> {
  // ...
}
```

**Overloaded/union-heavy functions:**
Describe the general behavior rather than each possible overload or union
variant.

### Rust Rules

**Comment style**: Use `///` triple-slash line comments for item docs. Keep
lines around 80 characters.

**Structure:**
- First line: brief summary sentence.
- Blank `///` line, then details or examples as needed.
- For fallible functions, add a `# Errors` section if the error conditions are
  clear from the signature.
- Refer to types with backticks: `` `SomeType` ``.

**Scope**: Only document public API by default (`pub fn`, `pub struct`,
`pub enum`, `pub trait`, pub methods on pub types).

**Mode behavior:**
- `update_missing`: Only add docs to items without existing `///` comments.
- `update_all`: Refine awkward wording but preserve explicit notes like
  `# Panics` or `# Safety`.

From espennilsen/pi, MIT.

More from espennilsen/pi