[docs-utils] 4️⃣ Extract destructured param property JSDoc by clintandrewhall · Pull Request #250813 · elastic/kibana

clintandrewhall · 2026-01-28T19:58:02Z

Summary

Implements extraction of JSDoc @param comments for nested properties using dot notation (e.g., @param obj.prop, @param fns.fn1.foo.param). This allows documentation of individual properties within destructured function parameters.

Note

This PR is a subset of #247688 for ease of review.

This PR was written with Cursor and claude-4.5-opus-high.

Important

This PR relies on #250810 and includes it as its base commit. This PR will remain draft until that PR is merged and this branch is rebased.

Before / After Example

Given this JSDoc-annotated function:

/**
 * Who would write such a complicated function?? Ewwww.
 *
 * @param {Object} obj A very crazy parameter.
 * @param {string} obj.hi Greeting on the obj.
 * @param {Object} fns A destructured object containing two functions.
 * @param {Function} fns.fn1 The first function.
 * @param {Function} fns.fn2 The second function.
 * @param {Object} fns.fn1.foo A parameter object for fn1.
 * @param {string} fns.fn1.foo.param A nested parameter for foo.
 */
export const crazyFunction = (
  obj: { hi: string },
  fns: { fn1: (foo: { param: string }) => number; fn2: () => void },
) => { /* ... */ };

Before this PR:

The generated API docs had empty descriptions for destructured parameters:

{
  "label": "obj",
  "description": [],
  "children": [{
    "label": "hi",
    "description": []   // <-- Missing! @param obj.hi was ignored
  }]
},
{
  "label": "fns",
  "description": [],
  "children": [{
    "label": "fn1",
    "description": [],  // <-- Missing! @param fns.fn1 was ignored
    "children": [{
      "label": "foo",
      "description": [],  // <-- Missing! @param fns.fn1.foo was ignored
      "children": [{
        "label": "param",
        "description": []  // <-- Missing! @param fns.fn1.foo.param was ignored
      }]
    }]
  }]
}

After this PR:

Dot-notation @param tags are now correctly extracted:

{
  "label": "obj",
  "description": ["A very crazy parameter."],
  "children": [{
    "label": "hi",
    "description": ["Greeting on the obj."]  // ✅ Extracted!
  }]
},
{
  "label": "fns",
  "description": ["A destructured object containing two functions."],
  "children": [{
    "label": "fn1",
    "description": ["The first function."],  // ✅ Extracted!
    "children": [{
      "label": "foo",
      "description": ["A parameter object for fn1."],  // ✅ Extracted!
      "children": [{
        "label": "param",
        "description": ["A nested parameter for foo."]  // ✅ Extracted!
      }]
    }]
  }]
}

Changes

Add ParamCommentCache to pre-parse all @param entries once per function, avoiding quadratic re-parsing for deep parameter structures
Implement applyParamComments() to recursively apply JSDoc comments to API declarations and their children
Fix potential crash when @param tag has no name token (e.g., malformed @param {string})
Fix suffix matching that could incorrectly attach @param options.foo to an unrelated parameter named foo
Update test fixtures to use named parameters with comprehensive dot-notation JSDoc
Fix typo: "arguements" → "arguments"

Impact

Missing comments count reduced from 76 to 64 for the test plugin
Destructured parameters now show their JSDoc descriptions in generated API docs

Copilot

Pull request overview

This PR implements extraction of JSDoc @param comments for nested properties in destructured function parameters using dot notation (e.g., @param obj.prop, @param fns.fn1.foo.param). This allows individual properties within destructured parameters to be documented in generated API docs.

Changes:

Implements parameter comment cache to avoid re-parsing JSDoc for deep structures
Adds dot-notation parameter matching logic
Updates fixture code to use named parameters with property-level JSDoc
Fixes typo: "arguements" → "arguments"
Reduces missing comments count from 76 to 64 in test plugin

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/kbn-docs-utils/src/types.ts	Adds `IssuesByPlugin` interface to group validation issues for cleaner function signatures
packages/kbn-docs-utils/src/stats.ts	Refactors `collectApiStatsForPlugin` to accept grouped issues via new interface
packages/kbn-docs-utils/src/stats.test.ts	Updates tests to use `IssuesByPlugin` and adds helper for empty issues
packages/kbn-docs-utils/src/cli/tasks/collect_stats.ts	Updates call site to use new grouped issues parameter
packages/kbn-docs-utils/src/build_api_declarations/js_doc_utils.ts	Implements dot-notation parameter matching and raw JSDoc parsing for nested properties
packages/kbn-docs-utils/src/build_api_declarations/js_doc_utils.test.ts	Updates tests to verify property-level JSDoc extraction works
packages/kbn-docs-utils/src/build_api_declarations/build_parameter_decs.ts	Adds `ParamCommentCache` and `applyParamComments` for efficient recursive comment application
packages/kbn-docs-utils/src/build_api_declarations/build_api_declaration.test.ts	Updates tests to verify nested destructured parameter comments are extracted
packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts	Updates tests to verify property-level validation works and renames parameters
packages/kbn-docs-utils/src/integration_tests/fixtures/src/plugin_a/public/plugin.ts	Updates expected missing comments count and removes resolved items from list
packages/kbn-docs-utils/src/integration_tests/fixtures/src/plugin_a/public/fns.ts	Refactors to use named parameters, adds comprehensive dot-notation JSDoc, fixes typo
packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_b.mdx	Updates generated date
packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a_foo.mdx	Updates missing comments count and date
packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.stats.json	Removes resolved missing comments entries and updates line numbers
packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.mdx	Updates missing comments count and date
packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.devdocs.json	Adds property descriptions, updates line numbers, changes parameter labels from destructured to named
packages/kbn-docs-utils/src/README.md	Improves documentation structure and clarity

packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.devdocs.json

packages/kbn-docs-utils/src/README.md

mistic

lgtm

elasticmachine · 2026-02-04T21:20:11Z

Pinging @elastic/kibana-operations (Team:Operations)

…ters Implements extraction of JSDoc `@param` comments for nested properties using dot notation (e.g., `@param obj.prop`, `@param fns.fn1.foo.param`). This allows documentation of individual properties within destructured function parameters. Changes: - Add `ParamCommentCache` to pre-parse all `@param` entries once per function, avoiding quadratic re-parsing for deep parameter structures - Implement `applyParamComments()` to recursively apply JSDoc comments to API declarations and their children - Fix potential crash when `@param tag` has no name token (e.g., malformed `@param {string}`) - Fix suffix matching that could incorrectly attach `@param options.foo` to an unrelated parameter named `foo` - Update test fixtures to use named parameters with comprehensive dot-notation JSDoc - Fix typo: "arguements" → "arguments" Impact: - Missing comments count reduced from 76 to 64 for the test plugin - Destructured parameters now show their JSDoc descriptions in generated API docs

elasticmachine · 2026-02-10T21:07:48Z

💚 Build Succeeded

Buildkite Build
Commit: 45f33b1

Metrics [docs]

Public APIs missing comments

Total count of every public API that lacks a comment. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats comments for more detailed information.

id	before	after	diff
`@kbn/aiops-utils`	0	2	+2
`@kbn/chart-expressions-common`	82	80	-2
`@kbn/cloud-security-posture-graph`	59	58	-1
`@kbn/config-schema`	145	142	-3
`@kbn/core-application-browser`	27	25	-2
`@kbn/core-chrome-layout-utils`	13	3	-10
`@kbn/core-http-server`	248	247	-1
`@kbn/core-saved-objects-api-server`	26	38	+12
`@kbn/core-test-helpers-kbn-server`	58	60	+2
`@kbn/core-user-profile-browser`	4	5	+1
`@kbn/elastic-assistant`	178	169	-9
`@kbn/elastic-assistant-common`	706	705	-1
`@kbn/esql-language`	689	677	-12
`@kbn/esql-utils`	133	139	+6
`@kbn/ftr-common-functional-ui-services`	521	520	-1
`@kbn/import-resolver`	40	38	-2
`@kbn/inference-common`	173	172	-1
`@kbn/json-ast`	35	30	-5
`@kbn/json-schemas`	7	6	-1
`@kbn/lens-common`	1361	1359	-2
`@kbn/ml-data-grid`	6	12	+6
`@kbn/ml-date-utils`	0	1	+1
`@kbn/react-hooks`	23	25	+2
`@kbn/repo-linter`	38	32	-6
`@kbn/repo-path`	9	7	-2
`@kbn/scout`	235	234	-1
`@kbn/scout-oblt`	241	240	-1
`@kbn/scout-search`	230	229	-1
`@kbn/scout-security`	243	242	-1
`@kbn/shared-ux-button-toolbar`	8	7	-1
`@kbn/telemetry-tools`	5	4	-1
`@kbn/workflows`	398	397	-1
`data`	2600	2612	+12
`dataViews`	451	452	+1
`expressions`	1805	1802	-3
`fieldFormats`	282	283	+1
`files`	24	22	-2
`fleet`	1666	1664	-2
`inspector`	112	114	+2
`lens`	609	607	-2
`savedObjects`	89	88	-1
`security`	238	239	+1
`visTypeTimeseries`	11	10	-1
total			-30

clintandrewhall assigned mistic Jan 28, 2026

clintandrewhall added review Team:Operations Kibana-Operations Team release_note:skip Skip the PR/issue when compiling release notes backport:skip This PR does not require backporting v9.4.0 labels Jan 28, 2026

clintandrewhall unassigned mistic Jan 28, 2026

clintandrewhall requested review from Copilot and mistic January 28, 2026 21:36

Copilot AI reviewed Jan 28, 2026

View reviewed changes

packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.devdocs.json Outdated Show resolved Hide resolved

packages/kbn-docs-utils/src/README.md Outdated Show resolved Hide resolved

packages/kbn-docs-utils/src/README.md Outdated Show resolved Hide resolved

clintandrewhall mentioned this pull request Jan 29, 2026

[meta] Updating @kbn/docs-utils, add MCP tools #247688

Draft

13 tasks

clintandrewhall changed the title ~~[docs-utils] Extract property JSDoc for destructured params~~ [docs-utils] 4️⃣ Extract destructured param property JSDoc Jan 29, 2026

mistic approved these changes Feb 4, 2026

View reviewed changes

clintandrewhall marked this pull request as ready for review February 4, 2026 21:20

clintandrewhall requested a review from a team as a code owner February 4, 2026 21:20

clintandrewhall added 3 commits February 10, 2026 14:46

Test updates

4930864

Address feedback

45f33b1

clintandrewhall force-pushed the feat/docs-utils/4-destructured-params branch from ff1940f to 45f33b1 Compare February 10, 2026 19:48

clintandrewhall enabled auto-merge (squash) February 10, 2026 19:48

clintandrewhall merged commit 8cf343d into elastic:main Feb 10, 2026
16 checks passed

clintandrewhall deleted the feat/docs-utils/4-destructured-params branch February 10, 2026 21:06

clintandrewhall mentioned this pull request Mar 13, 2026

[docs-utils] Add fix-package-docs skill #257577

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs-utils] 4️⃣ Extract destructured param property JSDoc#250813

[docs-utils] 4️⃣ Extract destructured param property JSDoc#250813
clintandrewhall merged 3 commits intoelastic:mainfrom
clintandrewhall:feat/docs-utils/4-destructured-params

clintandrewhall commented Jan 28, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mistic left a comment

Uh oh!

elasticmachine commented Feb 4, 2026

Uh oh!

Uh oh!

elasticmachine commented Feb 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

clintandrewhall commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Before / After Example

Changes

Impact

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mistic left a comment

Choose a reason for hiding this comment

Uh oh!

elasticmachine commented Feb 4, 2026

Uh oh!

Uh oh!

elasticmachine commented Feb 10, 2026

💚 Build Succeeded

Metrics [docs]

Public APIs missing comments

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

clintandrewhall commented Jan 28, 2026 •

edited

Loading