Summary

Adds a new missingReturns validation to the kbn-docs-utils API stats collection. This tracks functions that are missing @returns JSDoc documentation, helping improve API documentation quality across the codebase.

Before / After Example

Given these TypeScript functions:

/** Fetches user data from the API. */
export const getUser = (id: string): Promise<User> => {
  return fetchFromApi(`/users/${id}`);
};

/** Logs a message to the console. */
export const logMessage = (msg: string): void => {
  console.log(msg);
};

/**
 * Creates a new search service.
 * @returns The initialized search service.
 */
export const createSearchService = (): SearchService => {
  return new SearchService();
};

Before this PR:

No validation existed for missing @returns documentation. Functions without return documentation passed silently:

{
  "counts": {
    "missingComments": 0
  }
}

After this PR:

Functions missing @returns are now flagged separately:

{
  "counts": {
    "missingComments": 0,
    "missingReturns": 1     // ✅ getUser flagged (non-void, no @returns)
  },
  "missingReturns": [
    {
      "id": "def-public.getUser",
      "label": "getUser",
      "type": "Function",
      "lineNumber": 2
    }
    // logMessage NOT flagged (returns void - no @returns needed)
    // createSearchService NOT flagged (has @returns comment)
  ]
}

Smart Void Exclusion

Functions returning void-like types are automatically excluded since they don't need @returns documentation:

Changes

• New missingReturns stat - Added to ApiStats interface to track functions without return documentation.
• Function detection - Identifies function-like declarations via TypeKind.FunctionKind or arrow syntax (=>) in signatures.
• Smart void exclusion - Excludes functions with void-like returns (void, undefined, Promise<void>, Promise<undefined>) since these don't require @returns documentation.
• Fixture script update - Updated update_fixture_comments.js to include the new missingReturns category.

Impact

• Test plugin shows 23 functions missing @returns documentation
• Validation integrated with --check comments flag in check_package_docs