[docs-utils] 4️⃣ Add param doc mismatch validation

packages/kbn-docs-utils/scripts/update_fixture_comments.js

@@ -12,6 +12,7 @@ const path = require('node:path');
 
 const categories = [
   { key: 'missingComments', title: 'missing comments' },
+  { key: 'paramDocMismatches', title: 'param doc mismatches' },
   { key: 'isAnyType', title: 'any usage' },
   { key: 'noReferences', title: 'no references' },
 ];

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

@@ -1,4 +1,4 @@
-# Autogenerated API documentation
+# Auto-generated API documentation.
 
 [RFC](https://github.com/elastic/kibana/blob/main/legacy_rfcs/text/0014_api_documentation.md)
 

packages/kbn-docs-utils/src/__test_helpers__/mocks.ts

@@ -65,6 +65,7 @@ export const createMockPluginStats = (overrides: Partial<ApiStats> = {}): ApiSta
   missingComments: [],
   isAnyType: [],
   noReferences: [],
+  paramDocMismatches: [],
   missingExports: 0,
   deprecatedAPIsReferencedCount: 0,
   unreferencedDeprecatedApisCount: 0,
@@ -95,6 +96,7 @@ export const createMockPluginMetaInfo = (
   missingComments: [],
   isAnyType: [],
   noReferences: [],
+  paramDocMismatches: [],
   missingExports: 0,
   deprecatedAPIsReferencedCount: 0,
   unreferencedDeprecatedApisCount: 0,

packages/kbn-docs-utils/src/check_package_docs_cli.test.ts

@@ -42,6 +42,7 @@ const createBaseStats = (pluginId: string): AllPluginStats => ({
     missingComments: [],
     isAnyType: [],
     noReferences: [],
+    paramDocMismatches: [],
     apiCount: 0,
     missingExports: 0,
     deprecatedAPIsReferencedCount: 0,

packages/kbn-docs-utils/src/check_package_docs_cli.ts

@@ -83,7 +83,9 @@ export const getValidationResults = (
         : 0;
 
       const hasAnyIssues = shouldCheckAny && pluginStats.isAnyType.length > 0;
-      const hasCommentIssues = shouldCheckComments && pluginStats.missingComments.length > 0;
+      const hasCommentIssues =
+        shouldCheckComments &&
+        (pluginStats.missingComments.length > 0 || pluginStats.paramDocMismatches.length > 0);
       const hasExportIssues = shouldCheckExports && missingExports > 0;
 
       return {

packages/kbn-docs-utils/src/cli/tasks/collect_stats.test.ts

@@ -77,6 +77,7 @@ describe('collectStats', () => {
       missingComments: [],
       isAnyType: [],
       noReferences: [],
+      paramDocMismatches: [],
       missingExports: 0,
       deprecatedAPIsReferencedCount: 0,
       unreferencedDeprecatedApisCount: 0,

packages/kbn-docs-utils/src/cli/tasks/report_metrics.test.ts

@@ -80,6 +80,7 @@ describe('reportMetrics', () => {
         missingComments: [],
         isAnyType: [],
         noReferences: [],
+        paramDocMismatches: [],
         missingExports: 0,
         deprecatedAPIsReferencedCount: 0,
         unreferencedDeprecatedApisCount: 0,

packages/kbn-docs-utils/src/cli/tasks/write_docs.test.ts

@@ -92,6 +92,7 @@ describe('writeDocs', () => {
         missingComments: [],
         isAnyType: [],
         noReferences: [],
+        paramDocMismatches: [],
         missingExports: 0,
         deprecatedAPIsReferencedCount: 0,
         unreferencedDeprecatedApisCount: 0,

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts

@@ -128,6 +128,10 @@ export interface IReturnAReactComponent {
 //     line 71 - CrazyClass
 //     line 94 - foo
 //     line 117 - component
+//   param doc mismatches (3):
+//     line 52 - Constructor
+//     line 91 - anOptionalFn
+//     line 101 - fnTypeWithGeneric
 //   no references (23):
 //     line 28 - WithGen
 //     line 32 - t

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts

@@ -87,6 +87,10 @@ export const literalString = 'HI';
 //   missing comments (2):
 //     line 32 - a
 //     line 45 - foo
+//   param doc mismatches (3):
+//     line 19 - notAnArrowFn
+//     line 24 - aPropertyMisdirection
+//     line 29 - aPropertyInlineFn
 //   no references (14):
 //     line 18 - aPretendNamespaceObj
 //     line 19 - notAnArrowFn

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts

@@ -109,6 +109,9 @@ export const iShouldBeInternalFn = () => 'hi';
 //     line 83 - a
 //     line 83 - fnWithNonExportedRef
 //     line 85 - NotAnArrowFnType
+//   param doc mismatches (2):
+//     line 83 - fnWithNonExportedRef
+//     line 85 - NotAnArrowFnType
 //   no references (40):
 //     line 13 - notAnArrowFn
 //     line 24 - a

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts

@@ -45,6 +45,8 @@ export function plugin() {
 //     line 30 - config
 //     line 30 - foo
 //     line 30 - new
+//   param doc mismatches (1):
+//     line 30 - new
 //   any usage (1):
 //     line 20 - imAnAny
 //   no references (9):

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/plugin.ts

@@ -186,6 +186,8 @@ export class PluginA implements PluginMock<Setup, Start> {
 //     line 135 - fn
 //     line 135 - foo
 //     line 135 - param
+//   param doc mismatches (1):
+//     line 135 - fn
 //   no references (23):
 //     line 19 - SearchSpec
 //     line 24 - username

packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts

@@ -80,6 +80,10 @@ export type AReactElementFn = () => ReactElement<MyProps>;
 //     line 61 - foo
 //     line 62 - bar
 //     line 65 - AReactElementFn
+//   param doc mismatches (3):
+//     line 30 - FnTypeWithGeneric
+//     line 54 - foo
+//     line 62 - bar
 //   no references (21):
 //     line 14 - StringOrUndefinedType
 //     line 19 - TypeWithGeneric

packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts

@@ -152,10 +152,12 @@ beforeAll(async () => {
       apiCount: pluginAStats.apiCount,
       missingExports: pluginAStats.missingExports,
       missingComments: pluginAStats.missingComments.length,
+      paramDocMismatches: pluginAStats.paramDocMismatches.length,
       isAnyType: pluginAStats.isAnyType.length,
       noReferences: pluginAStats.noReferences.length,
     },
     missingComments: pluginAStats.missingComments.map(mapStat),
+    paramDocMismatches: pluginAStats.paramDocMismatches.map(mapStat),
     isAnyType: pluginAStats.isAnyType.map(mapStat),
     noReferences: pluginAStats.noReferences.map(mapStat),
   };

packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a.mdx

@@ -8,7 +8,7 @@ slug: /kibana-dev-docs/api/pluginA
 title: "pluginA"
 image: https://source.unsplash.com/400x175/?github
 description: API docs for the pluginA plugin
-date: 2026-01-28
+date: 2026-02-10
 tags: ['contributor', 'dev', 'apidocs', 'kibana', 'pluginA']
 ---
 import pluginAObj from './plugin_a.devdocs.json';

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

@@ -3,6 +3,7 @@
     "apiCount": 136,
     "missingExports": 2,
     "missingComments": 64,
+    "paramDocMismatches": 13,
     "isAnyType": 1,
     "noReferences": 135
   },
@@ -520,6 +521,112 @@
       "columnNumber": 3
     }
   ],
+  "paramDocMismatches": [
+    {
+      "id": "def-public.Setup.fnWithInlineParams.$1.fn",
+      "label": "fn",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/plugin.ts",
+      "type": "Function",
+      "lineNumber": 135,
+      "columnNumber": 5
+    },
+    {
+      "id": "def-public.ClassConstructorWithStaticProperties.new",
+      "label": "new",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/index.ts",
+      "type": "Function",
+      "lineNumber": 30,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.fnWithNonExportedRef",
+      "label": "fnWithNonExportedRef",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts",
+      "type": "Function",
+      "lineNumber": 83,
+      "columnNumber": 14
+    },
+    {
+      "id": "def-public.NotAnArrowFnType",
+      "label": "NotAnArrowFnType",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/fns.ts",
+      "type": "Type",
+      "lineNumber": 85,
+      "columnNumber": 1
+    },
+    {
+      "id": "def-public.ExampleClass.Unnamed",
+      "label": "Constructor",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts",
+      "type": "Function",
+      "lineNumber": 52,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.ExampleInterface.anOptionalFn",
+      "label": "anOptionalFn",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts",
+      "type": "Function",
+      "lineNumber": 91,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.ExampleInterface.fnTypeWithGeneric",
+      "label": "fnTypeWithGeneric",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/classes.ts",
+      "type": "Function",
+      "lineNumber": 101,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.aPretendNamespaceObj.notAnArrowFn",
+      "label": "notAnArrowFn",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts",
+      "type": "Function",
+      "lineNumber": 19,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.aPretendNamespaceObj.aPropertyMisdirection",
+      "label": "aPropertyMisdirection",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts",
+      "type": "Function",
+      "lineNumber": 24,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.aPretendNamespaceObj.aPropertyInlineFn",
+      "label": "aPropertyInlineFn",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/const_vars.ts",
+      "type": "Function",
+      "lineNumber": 29,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.FnTypeWithGeneric",
+      "label": "FnTypeWithGeneric",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts",
+      "type": "Type",
+      "lineNumber": 30,
+      "columnNumber": 1
+    },
+    {
+      "id": "def-public.ImAnObject.foo",
+      "label": "foo",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts",
+      "type": "Function",
+      "lineNumber": 54,
+      "columnNumber": 3
+    },
+    {
+      "id": "def-public.MyProps.bar",
+      "label": "bar",
+      "path": "packages/kbn-docs-utils/src/integration_tests/__fixtures__/src/plugin_a/public/types.ts",
+      "type": "Function",
+      "lineNumber": 62,
+      "columnNumber": 3
+    }
+  ],
   "isAnyType": [
     {
       "id": "def-public.imAnAny",

packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_a_foo.mdx

@@ -8,7 +8,7 @@ slug: /kibana-dev-docs/api/pluginA-foo
 title: "pluginA.foo"
 image: https://source.unsplash.com/400x175/?github
 description: API docs for the pluginA.foo plugin
-date: 2026-01-28
+date: 2026-02-10
 tags: ['contributor', 'dev', 'apidocs', 'kibana', 'pluginA.foo']
 ---
 import pluginAFooObj from './plugin_a_foo.devdocs.json';

packages/kbn-docs-utils/src/integration_tests/snapshots/plugin_b.mdx

@@ -8,7 +8,7 @@ slug: /kibana-dev-docs/api/pluginB
 title: "pluginB"
 image: https://source.unsplash.com/400x175/?github
 description: API docs for the pluginB plugin
-date: 2026-01-28
+date: 2026-02-10
 tags: ['contributor', 'dev', 'apidocs', 'kibana', 'pluginB']
 ---
 import pluginBObj from './plugin_b.devdocs.json';