Fix API documentation issues in a Kibana plugin or package. Use when asked to fix, improve, or add JSDoc/API documentation for a Kibana plugin or package, or when check_package_docs validation fails.
Fix API documentation issues in a Kibana plugin or package. Use when asked to fix, improve, or add JSDoc/API documentation for a Kibana plugin or package, or when check_package_docs validation fails.
disable-model-invocation
true
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>.
for cross-references to other Kibana types.
Use {@link OtherType}
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.
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:
missingComments — highest volume, most impact
missingReturns — quick wins (add @returns to existing JSDoc)
paramDocMismatches — add missing @param tags so all params are documented
missingComplexTypeInfo — add JSDoc to undocumented interface, object, and union type declarations
isAnyType — replace any with specific types (careful: may require reading more context)
unnamedExports — skip; flag for human review (requires restructuring exports, which changes the public API surface)
missingExports — skip; flag for human review
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.
*
* @paramfilters - Array of filter objects to sanitize.
* @returns Cleaned filter array safe for serialization.
*/exportfunctioncleanFiltersForSerialize(filters: Filter[]): Filter[] {
Interfaces/types:
/**
* Parameters for retrieving a dashboard by its saved object ID.
*/exportinterfaceGetDashboardParams {
Interface properties (inline /** ... */):
exportinterfaceDashboardLocatorParams {
/** 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. */exportconstMAX_PANELS = 100;
Classes:
/**
* Provides the public API for the Dashboard plugin.
*/exportclassDashboardPluginimplementsPlugin<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.
*
* @paramstate - Current dashboard application state.
* @returns Locator params derived from the state, suitable for deep-linking.
*/
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.
*
* @paramid - The user ID.
*/exportconst getUser = (id: string, includeRoles: boolean, timeout?: number): Promise<User> => { /* ... */ };
// After: all params documented/**
* Fetches user data from the API.
*
* @paramid - The user ID.
* @paramincludeRoles - When true, includes the user's assigned roles in the response.
* @paramtimeout - Optional request timeout in milliseconds.
*/exportconst 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.
*
* @paramquery - The query object.
* @param query.text - The search string.
* @param query.language - Query language (e.g., `kuery`, `lucene`).
* @paramoptions - Runtime options.
* @param options.signal - Abort signal for cancellation.
*/exportconstrunSearch = (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 FilterSpecexportinterfaceSearchOptions {
query: string;
filters: FilterSpec;
}
exporttypeFilterSpec = {
field: string;
operator: 'eq' | 'neq';
};
// After/**
* Options for configuring a search request.
*/exportinterfaceSearchOptions {
query: string;
filters: FilterSpec;
}
/**
* Describes a single filter condition applied to a search query.
*/exporttypeFilterSpec = {
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:
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."
