Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

maintain-jsdocs

/maintain-jsdocs

Utrzymuje JSDoc na eksportowanych deklaracjach tak, by wygenerowana referencja API nie miała luk w pokryciu, także dla całego repozytorium lub wybranych plików.

Repozytorium
pikacss ↗
Licencja
MIT
Ostatnia zmiana repozytorium
05.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 05.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Utrzymuje JSDoc na eksportowanych deklaracjach tak, by wygenerowana referencja API nie miała luk w pokryciu, także dla całego repozytorium lub wybranych plików.

Oryginalny opis (EN)

Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.

Jak działa

  1. Scope
  2. The contract
  3. Workflow
  4. Quality bar
  5. References
Sekcje z nagłówków SKILL.md, w oryginale · 80 linii, 507 słów
Podgląd SKILL.md
---
name: maintain-jsdocs
description: 'Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.'
---

# Maintain JSDocs

## Scope

- JSDoc only. README and docs pages are out of scope unless the request says otherwise.
- Covers **all exported declarations** in every source file of a package, not just what `index.ts` re-exports, plus module augmentation members in plugin packages.
- Includes `@internal` exports: gen-api skips them, but their JSDoc is still maintained.
- Excludes `dist/`, `coverage/`, `*.test.ts`, `*.spec.ts`, `pika.gen.*`, `generated-*.ts`.
- English only.

Package directories in this repository: !`grep -o "dir: '[^']*'" "${CLAUDE_PROJECT_DIR}/scripts/_skill-shared/index.ts" | sed "s/dir: //;s/'//g" | tr '\n' ' '`

Ask which packages to process when the request does not say; use `AskUserQuestion` if it is available.

## The contract

`gen-api-docs` extracts JSDoc from `packages/*/src/index.ts` via the TypeScript compiler API. Every gap renders as "Missing JSDoc summary." on a published page, so the gap list is the definition of done:

| Export kind | Required |
|---|---|
| Function | Summary + `@param` description per parameter |
| Interface | Summary + description per property |
| Type alias | Summary |
| Constant / Variable | Summary |
| Class | Summary + description per public property and method, including constructor `@param`s |
| Module augmentation member | Description per property |

`collectCoverageGaps` in `scripts/maintain-docs/gen-api-docs.ts` is the authority. Read it when a gap report is surprising.

## Workflow

1. **Find the gaps.** `pnpm maintain-docs:gen-api` lists every coverage gap by package and symbol. Work from that list.
2. **Write the JSDoc** directly in the source file, reading the implementation and its call sites first.
3. **Validate**:

```bash
pnpm maintain-jsdocs:lint --packages <name>...   # corruption check
pnpm maintain-docs:gen-api                       # zero-gap check
pnpm --filter @pikacss/<name> typecheck
```

Repeat until gen-api reports `✅ No JSDoc coverage gaps detected.`

For large scopes, process one package per subagent in parallel rather than sweeping serially.

### Full restart (opt in, destructive)

`pnpm maintain-jsdocs:scaffold --packages <name>...` **replaces** existing JSDoc on every exported declaration with `@todo FILL:` templates, then you fill each marker and remove the tag.

Use it only when the existing JSDoc for a package is being rewritten wholesale on purpose. It discards good prose along with bad, so gap-driven editing is the default.

## Quality bar

Beyond zero-gap: every sentence must add something the type signature does not already say. "Returns the resolved engine configuration after plugin normalization" over "Returns a ResolvedEngineConfig".

Repo-specific conventions the generator and readers rely on:

- `@default` on every optional interface property — the effective value or behavior when omitted, literals in inline code.
- `@example` with a fenced `ts` block when usage is ordering-sensitive, composable, or easy to misuse.
- `@remarks` for lifecycle, hook interaction, and cross-package relationships — this is where PikaCSS's non-obvious behavior belongs.
- Each JSDoc tag starts its own real line. Never emit literal `\n` or `\t` inside a comment; `maintain-jsdocs:lint` fails on both.

```ts
declare module '@pikacss/core' {
  interface EngineConfig {
    /**
     * CSS reset style injected as a preflight, before utility styles.
     *
     * @default 'tailwind-preflight'
     */
    reset?: ResetStyle
  }
}
```

## References

- [workflow-rules.md](references/workflow-rules.md) — format conventions and the quality checklist.
Pliki w paczce (2)
  • SKILL.md 4 KB
  • references/workflow-rules.md 7 KB

Wersje

W bazie nie ma innych skilli o nazwie maintain-jsdocs.

Migawka bazy z 13.11.2026 · wersja paczki a1244b534f76 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 96jsdocs
    Pisze i przegląda dokumentację JSDoc publicznego API, dbając o spójność z modułami Effect.
  • 100write-component-jsdocs
    Pisze i sprawdza komentarze JSDoc dla komponentów vapor-ui i ich propsów, dobierając miejsce do wzorca komponentu.
  • 100jsdoc-comment-generator
    Prawdopodobnie generuje komentarze JSDoc i wspiera dokumentację techniczną.
  • 100jsdoc
    Obsługuje JSDoc, generator dokumentacji dla JavaScript z adnotacjami typów: komentarze jsdoc, wskazówki typów i generowanie dokumentacji API.
  • 95jsdoc-guide
    Podpowiada zasady pisania JSDoc i komentarzy w kodzie, tak by dokumentacja funkcji była spójna i nadawała się do generowania.
  • 100documentation
    Generuje docstringi, JSDoc, dokumentację API i aktualizacje README, które odzwierciedlają bieżący kod.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.