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.
Systematically find and fix all actionable API documentation issues in a Kibana plugin or package using check_package_docs.
/** ... */ style (not //). Single-line /** Description. */ for simple items; multi-line for complex ones.@param name - Description. (hyphen separator, not colon). Match every parameter in the signature.@param options.foo - Description.). The tooling supports arbitrary nesting (e.g., @param fns.fn1.foo.param). Each level must have its own @param tag.@returnsvoidPromise<void>{@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.Given a plugin ID (e.g., dashboard), manifest ID (e.g., @kbn/dashboard-plugin), or file path:
--plugin <id>--package <id>kibana.jsonc)To confirm: search for the plugin.id in kibana.jsonc files if unsure.
grep -r '"id": "dashboard"' --include="kibana.jsonc" -l
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.
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:
missingComments — highest volume, most impactmissingReturns — quick wins (add @returns to existing JSDoc)paramDocMismatches — add missing @param tags so all params are documentedmissingComplexTypeInfo — add JSDoc to undocumented interface, object, and union type declarationsisAnyType — 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 reviewnoReferences — informational only; not a validation failure, no action requiredFor each file, read it fully first, then make all edits in one pass.
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> {
@returns to existing JSDocFind 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.
*/
@param documentationThis 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.).
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.
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.
any with specific typesRead the context to understand the actual type, then replace. Common patterns:
// Before