[docs-utils] 4️⃣ Improve missing comments detection

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();
     });
 

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;