fix-package-docs

Fix Package Docs

Systematically find and fix all actionable API documentation issues in a Kibana plugin or package using check_package_docs.

Non-negotiable conventions

• Only add JSDoc to exported public API — skip internal helpers that happen to be exported.
• Never change runtime behavior — documentation edits only (no logic, type, or signature changes).
• Use /** ... */ style (not //). Single-line /** Description. */ for simple items; multi-line for complex ones.
• Descriptions are sentences: start with a capital letter, end with a period.
• @param name - Description. (hyphen separator, not colon). Match every parameter in the signature.
• Destructured object parameters: document nested properties with dot-notation tags (e.g., @param options.foo - Description.). The tooling supports arbitrary nesting (e.g., @param fns.fn1.foo.param). Each level must have its own @param tag.
• @returns for non-void functions: always present; omit only for void/Promise<void>.
• Use {@link OtherType} for cross-references to other Kibana types.
• missingExports items need human judgment to decide whether to export — skip them and note in PR.

Workflow

1. Resolve the target

Given a plugin ID (e.g., dashboard), manifest ID (e.g., @kbn/dashboard-plugin), or file path:

• Plugin ID → use --plugin <id>
• Manifest ID / package name → use --package <id>
• File path → find its package first (look for nearest kibana.jsonc)

To confirm: search for the plugin.id in kibana.jsonc files if unsure.

grep -r '"id": "dashboard"' --include="kibana.jsonc" -l

2. Generate the stats file

node scripts/check_package_docs.js --plugin <pluginId> --write
# or for packages:
node scripts/check_package_docs.js --package <manifestId> --write

This writes <pluginDir>/target/api_docs/stats.json with structured issue data. Exit code 1 is expected when issues exist — that's normal.

3. Read and plan

Read the stats file:

<pluginDir>/target/api_docs/stats.json

The file has this shape:

{
  "counts": {
    "apiCount": 145,
    "missingComments": 28,
    "missingReturns": 10,
    "paramDocMismatches": 5,
    "missingComplexTypeInfo": 8,
    "isAnyType": 3,
    "noReferences": 144,
    "missingExports": 11,
    "unnamedExports": 2
  },
  "missingComments": [
    { "id": "dashboard.SomeType", "label": "SomeType", "path": "src/.../types.ts", "type": "Interface", "lineNumber": 42, "link": "..." }
  ],
  "missingReturns": [...],
  "paramDocMismatches": [...],
  "missingComplexTypeInfo": [...],
  "isAnyType": [...],
  "noReferences": [...],
  "missingExports": [{ "source": "...", "references": [...] }],
  "unnamedExports": [{ "pluginId": "dashboard", "scope": "public", "path": "src/.../index.ts", "lineNumber": 12, "textSnippet": "export default { ... }" }]
}

Report a summary of the issues in a table before proceeding with fixes.

Group all issues by path so you edit each file once. Prioritize:

1. missingComments — highest volume, most impact
2. missingReturns — quick wins (add @returns to existing JSDoc)
3. paramDocMismatches — add missing @param tags so all params are documented
4. missingComplexTypeInfo — add JSDoc to undocumented interface, object, and union type declarations
5. isAnyType — replace any with specific types (careful: may require reading more context)
6. unnamedExports — skip; flag for human review (requires restructuring exports, which changes the public API surface)
7. missingExports — skip; flag for human review
8. noReferences — informational only; not a validation failure, no action required

4. Fix issues file by file

For each file, read it fully first, then make all edits in one pass.

missingComments — add JSDoc above the declaration

Functions/methods:

/**
 * Cleans filters before serialization by removing empty arrays and null values.
 *
 * @param filters - Array of filter objects to sanitize.
 * @returns Cleaned filter array safe for serialization.
 */
export function cleanFiltersForSerialize(filters: Filter[]): Filter[] {

Interfaces/types:

/**
 * Parameters for retrieving a dashboard by its saved object ID.
 */
export interface GetDashboardParams {

Interface properties (inline /** ... */):

export interface DashboardLocatorParams {
  /** The saved object ID of the dashboard to navigate to. */
  dashboardId?: string;
  /** When true, the dashboard opens in view mode. */
  viewMode?: boolean;
}

Constants/variables:

/** Maximum number of panels allowed on a single dashboard. */
export const MAX_PANELS = 100;

Classes:

/**
 * Provides the public API for the Dashboard plugin.
 */
export class DashboardPlugin implements Plugin<DashboardPluginSetup, DashboardPluginStart> {

missingReturns — add @returns to existing JSDoc

Find the existing JSDoc block and add the @returns line before the closing */. Match the actual return type:

/**
 * Retrieves the locator params for the current dashboard state.
 *
 * @param state - Current dashboard application state.
 * @returns Locator params derived from the state, suitable for deep-linking.
 */

paramDocMismatches — complete partial @param documentation

This flag means some (but not all) parameters already have @param tags — the function has inconsistent docs. Functions where no params are documented are not flagged here; they fall under missingComments instead.

The fix is always to add the missing @param tags so every parameter is covered. Read the function signature and add a @param for each undocumented parameter:

// Before: only `id` is documented, `includeRoles` and `timeout` are missing
/**
 * Fetches user data from the API.
 *
 * @param id - The user ID.
 */
export const getUser = (id: string, includeRoles: boolean, timeout?: number): Promise<User> => { /* ... */ };

// After: all params documented
/**
 * Fetches user data from the API.
 *
 * @param id - The user ID.
 * @param includeRoles - When true, includes the user's assigned roles in the response.
 * @param timeout - Optional request timeout in milliseconds.
 */
export const getUser = (id: string, includeRoles: boolean, timeout?: number): Promise<User> => { /* ... */ };

Also remove any stale @param entries for parameters that no longer exist in the signature.

Destructured object parameters — document each nested property with dot-notation tags. Every level of nesting needs its own @param:

/**
 * Runs a search with the given options.
 *
 * @param query - The query object.
 * @param query.text - The search string.
 * @param query.language - Query language (e.g., `kuery`, `lucene`).
 * @param options - Runtime options.
 * @param options.signal - Abort signal for cancellation.
 */
export const runSearch = (
  query: { text: string; language: string },
  options: { signal: AbortSignal },
) => { /* ... */ };

For deeply nested properties, continue the dot chain as far as needed (e.g., @param fns.fn1.foo.param - Description.).

missingComplexTypeInfo — add JSDoc to undocumented complex type declarations

A prioritized subset of missingComments for type declarations that lack a top-level JSDoc description. Flagged: interfaces, inline object types, and union/intersection types. Excluded: primitives and functions (self-documenting or tracked elsewhere). Fixing one reduces both missingComplexTypeInfo and missingComments counts.

The fix is to add a JSDoc block to the type declaration itself:

// Before — no description on SearchOptions or FilterSpec
export interface SearchOptions {
  query: string;
  filters: FilterSpec;
}

export type FilterSpec = {
  field: string;
  operator: 'eq' | 'neq';
};

// After
/**
 * Options for configuring a search request.
 */
export interface SearchOptions {
  query: string;
  filters: FilterSpec;
}

/**
 * Describes a single filter condition applied to a search query.
 */
export type FilterSpec = {
  field: string;
  operator: 'eq' | 'neq';
};

Inline property docs (e.g., /** ... */ on each field) are a separate concern covered under missingComments for interface members.

unnamedExports — flag for human review

This flags an exported declaration that has no identifiable name — meaning ts-morph cannot call getName() on the node. The most common cause is an anonymous export default expression (e.g., export default { ... } or export default function() { ... }).

Do not attempt to fix these. Naming an anonymous default export or removing export default changes the module's public API surface, which is a runtime behavior change outside the scope of documentation fixes. Report them in the PR for a developer to handle.

isAnyType — replace any with specific types

Read the context to understand the actual type, then replace. Common patterns:

// Before
callback: (result: any) => void
// After
callback: (result: DashboardCreationResult) => void

If the correct type is genuinely unknown, use unknown instead of any. Only change if you're confident — don't guess.

5. After each file, verify locally (optional)

For large plugins, re-run after batches of files to track progress:

node scripts/check_package_docs.js --plugin <pluginId> --write

Read the updated stats.json counts to confirm the numbers are going down.

6. Final verification

When all actionable issues are addressed:

node scripts/check_package_docs.js --plugin <pluginId>

Confirm All packages passed validation. (or only missingExports remain, which are pending human review).

Then run:

node scripts/check_changes.ts

7. PR notes

In the PR description, include:

• Before/after issue counts from stats.json
• Any missingExports or unnamedExports skipped (always skipped — flag for a developer)
• Any isAnyType items skipped because the correct type was ambiguous

Example: full run on the dashboard plugin

# Generate stats
node scripts/check_package_docs.js --plugin dashboard --write
# Read src/platform/plugins/shared/dashboard/target/api_docs/stats.json with the Read tool

# Fix all actionable issues across the plugin files per the rules above

# Verify
node scripts/check_package_docs.js --plugin dashboard
# → "All packages passed validation."