diff --git a/packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts b/packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts index 1da8607ffc720..2959303fba792 100644 --- a/packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts +++ b/packages/kbn-docs-utils/src/integration_tests/api_doc_suite.test.ts @@ -693,9 +693,8 @@ describe('validation and stats', () => { expect(missingComment).toBeDefined(); }); - it('validates missingComments includes destructured parameter children', () => { + it('does not flag destructured parameter children when documented', () => { // crazyFunction has destructured params with nested properties - // Current behavior: nested properties without comments are flagged const fn = doc.client.find((c) => c.label === 'crazyFunction'); expect(fn).toBeDefined(); @@ -705,34 +704,22 @@ describe('validation and stats', () => { const hiProp = objParam!.children?.find((c) => c.label === 'hi'); expect(hiProp).toBeDefined(); - // Current behavior: property without comment is flagged - // Note: This is a false positive that will be fixed in Phase 4.2 - // Verify the property structure exists and check if it's in missingComments expect(hiProp!.description).toBeDefined(); - const hasDescription = hiProp!.description!.length > 0; + expect(hiProp!.description!.length).toBeGreaterThan(0); const missingComment = pluginAStats.missingComments.find((d) => d.id === hiProp!.id); - - // If property has no description, it should be in missingComments - // If it has a description, it should not be in missingComments - if (!hasDescription) { - expect(missingComment).toBeDefined(); - } else { - expect(missingComment).toBeUndefined(); - } + expect(missingComment).toBeUndefined(); }); - it.skip('does not flag destructured params when `@param obj` exists', () => { + it('does not flag destructured params when `@param obj` exists', () => { const fn = doc.client.find((c) => c.label === 'crazyFunction'); expect(fn).toBeDefined(); const objParam = fn!.children?.find((c) => c.label === 'obj'); expect(objParam).toBeDefined(); expect(objParam!.description).toBeDefined(); - // Expected once fixed: the @param obj comment is captured. expect(objParam!.description!.length).toBeGreaterThan(0); const missingComment = pluginAStats.missingComments.find((d) => d.id === objParam!.id); - // Expected once fixed: the destructured param should not be flagged as missing. expect(missingComment).toBeUndefined(); }); diff --git a/packages/kbn-docs-utils/src/stats.ts b/packages/kbn-docs-utils/src/stats.ts index 217aa7f0d9407..619106260b8e0 100644 --- a/packages/kbn-docs-utils/src/stats.ts +++ b/packages/kbn-docs-utils/src/stats.ts @@ -67,7 +67,13 @@ function collectAdoptionTrackedAPIStats( } function collectStatsForApi(doc: ApiDeclaration, stats: ApiStats, pluginApi: PluginApi): void { - const missingComment = doc.description === undefined || doc.description.length === 0; + const hasDescription = doc.description !== undefined && doc.description.length > 0; + const childHasDescription = + doc.children?.some( + (child) => child.description !== undefined && child.description.length > 0 + ) ?? false; + const isParameterNode = doc.id.includes('.$'); // parameters and destructured parameter nodes carry .$ in their id + const missingComment = !hasDescription && !(isParameterNode && childHasDescription); // Ignore all stats coming from third party libraries, we can't fix that! if (doc.path.includes('node_modules')) return;