Summary

Adds a new paramDocMismatches validation to kbn-docs-utils that flags functions where not all parameters have JSDoc documentation. This complements the existing missingComments check, which only flags APIs that are completely undocumented.

Before / After Example

Given these TypeScript functions:

/**
 * Searches for documents matching the query.
 * @param query The search query string.   // ✅ Documented
 * @param options Search options.          // ✅ Documented
 */
export const search = (query: string, options: SearchOptions): Results => { /* ... */ };

/**
 * Fetches user data from the API.
 * @param id The user ID.                  // ✅ Documented
 */
export const getUser = (
  id: string,      // ✅ Has @param
  includeRoles: boolean,  // ❌ Missing @param!
  timeout?: number        // ❌ Missing @param!
): Promise<User> => { /* ... */ };

/** Logs a message. */  // No @param tags at all
export const log = (msg: string): void => { /* ... */ };

Before this PR:

No validation existed for partially-documented parameters. missingComments only flagged APIs with no description at all:

{
  "counts": {
    "missingComments": 0
  }
}
// getUser passes silently despite incomplete param docs!

After this PR:

Functions with incomplete parameter documentation are flagged:

{
  "counts": {
    "missingComments": 0,
    "paramDocMismatches": 1  // ✅ getUser flagged!
  },
  "paramDocMismatches": [
    {
      "id": "def-public.getUser",
      "label": "getUser",
      "type": "Function",
      "lineNumber": 8
    }
    // search NOT flagged (all params documented)
    // log NOT flagged (no params documented - all-or-nothing is OK)
  ]
}

Detection Logic

Why This Matters

Partial parameter documentation is worse than no documentation:

• Readers assume undocumented params are intentionally omitted
• Creates false confidence that docs are complete
• Often indicates docs fell out of sync with code changes

Changes

• ApiStats.paramDocMismatches: New field to track functions with incomplete parameter documentation
• isFunctionLike(): Helper function that detects function declarations and function-typed aliases by checking for TypeKind.FunctionKind or => in the signature
• trackParamDocMismatches(): Collects functions where some (but not all) parameters have descriptions
• Fixture script update - Updated update_fixture_comments.js to include the new paramDocMismatches category

Impact

• Test plugin shows 18 functions with incomplete parameter documentation
• Validation integrated with --check comments flag in check_package_docs