---
name: packages-documentation
description: Write, update, and format documentation for @data-client public APIs - API reference (Docusaurus/MDX), README files, JSDoc/TSDoc docstrings, usage examples, migration guides, deprecation notices, changelog entries. Use when changing exported APIs (docs must update in the same PR), writing new package docs, or updating the dataclient.io site.
license: Apache 2.0
metadata:
  internal: true
---
# Package Documentation Writing Guidelines

This guide covers how to write and format documentation for public library interfaces.

## Documentation Structure

The `/docs` folder is organized by package:
- `docs/core/` - Documentation for `@data-client/core`, `@data-client/react` and `@data-client/vue`
- `docs/rest/` - Documentation for `@data-client/rest`
- `docs/graphql/` - Documentation for `@data-client/graphql`

Each package documentation has subdirectories:
- `api/` - API reference documentation (one file per public class/function/hook)
- `guides/` - How-to guides and tutorials
- `concepts/` - Conceptual documentation
- `getting-started/` - Getting started guides

## React and Vue (single source)

`docs/core` renders twice: React at `/docs`, Vue at `/vue`. Never copy a page to make a Vue version.
Wrap framework-specific content instead, so shared prose and resources stay in one place:

- `:::react` / `:::vue` blocks (use `::::` on an outer admonition that contains them)
- `:react[...]` / `:vue[...]` for inline words or links
- `<FrameworkPlayground>` instead of `<HooksPlayground>`, with shared resource code blocks
  directly inside and component code blocks in `:::react` / `:::vue`
- `framework-imports` on a code fence for framework-agnostic code (managers, middleware): write
  `@data-client/react` imports and Vue pages show `@data-client/vue`. Examples never import
  `@data-client/core`; apps only install the react or vue package
- `vue_title:`, `vue_description:` (any `vue_<key>:`) front matter overrides
- `frameworks: [react]` front matter for pages with no Vue equivalent
- `foo.vue.md` replaces `foo.md` for Vue; only for Vue-only pages or when nothing is shareable

When changing a page, update both framework blocks in the same edit. See `website/framework-docs/README.md`.

## Documentation File Naming

API documentation files should match the exported name:
- `useSuspense.ts` → `docs/core/api/useSuspense.md`
- `RestEndpoint.js` → `docs/rest/api/RestEndpoint.md`
- `Controller.ts` → `docs/core/api/Controller.md`
- `Entity.ts` → `docs/rest/api/Entity.md` (or `docs/core/api/Entity.md`)

## Documentation Format

All API documentation files should include:

1. **Frontmatter** with metadata:
```markdown
---
title: API Name
sidebar_label: Display Name
---
```

2. **Description** - What the API does

3. **Usage examples** - Code examples showing how to use it

4. **Parameters/Options** - Document all parameters, options, and return types

5. **Type information** - TypeScript types and examples

6. **Related APIs** - Links to related documentation

## Finding the Right Documentation File

1. **Identify the package**: Check which package the code belongs to (`packages/core`, `packages/rest`, etc.)
2. **Check exports**: Look at the package's `index.ts` or main entry point to see what's exported
3. **Match the name**: Find the corresponding file in `docs/{package}/api/`
4. **Check guides**: If it's a workflow change, also check `docs/{package}/guides/`

## Examples

### Example 1: Adding a new hook
- **File**: `packages/react/src/hooks/useNewFeature.ts`
- **Action**: Create `docs/core/api/useNewFeature.md` with usage examples and API reference

### Example 2: Changing a method signature
- **File**: `packages/rest/src/RestEndpoint.js` (changing `extend()` method)
- **Action**: Update `docs/rest/api/RestEndpoint.md` with new signature, migration notes, and updated examples

### Example 3: Deprecating an API
- **File**: `packages/core/src/SomeClass.ts` (deprecating `oldMethod()`)
- **Action**: 
  - Update `docs/core/api/SomeClass.md` with deprecation notice
  - Document the replacement API
  - Add migration guide if needed

### Example 4: Adding a new option
- **File**: `packages/rest/src/RestEndpoint.js` (adding `newOption` parameter)
- **Action**: Update `docs/rest/api/RestEndpoint.md` to document the new option with examples

## Checklist

Before completing changes to public APIs in `/packages`:

- [ ] Identified all affected public APIs (exports from package entry points)
- [ ] Located or created corresponding documentation files in `/docs/{package}/api/`
- [ ] Updated API reference documentation with changes
- [ ] Added/updated code examples
- [ ] Updated related guides if workflow changed
- [ ] Added migration notes for breaking changes
- [ ] Updated TypeScript examples in documentation
- [ ] Verified documentation builds correctly (if applicable)
- [ ] Updated agent skills in `.agents/skills` that cover the API: `references.json` for added/renamed/deleted pages, and `SKILL.md` examples (see `.cursor/rules/skills-sync.mdc`)

## Important Notes

- **Public APIs** are anything exported from the package's main entry point (typically `index.ts` or `src/index.ts`)
- **Internal/private APIs** (prefixed with `_`, not exported, or marked as `@internal`) don't require documentation updates
- When in doubt, **err on the side of documenting** - it's better to have extra documentation than missing documentation
- Documentation should be updated **in the same commit or PR** as the code changes