## Summary

Improves the `missingComments` detection in `kbn-docs-utils` to avoid
false positives on destructured parameter nodes. Previously, a parameter
like `obj` in `crazyFunction(obj: {hi: string})` was flagged as missing
a comment even when its children (`obj.hi`) were individually documented
via JSDoc.

> [!NOTE]
> This PR is a subset of elastic#247688
for ease of review.
>
> This PR was written with Cursor and `claude-4.5-opus-high`.

### Before / After Example

Given this JSDoc-annotated function:

```typescript
/**
 * Who would write such a complicated function?? Ewwww.
 *
 * @param {Object} obj A very crazy parameter.
 * @param {string} obj.hi Greeting on the obj.
 */
export const crazyFunction = (
  obj: { hi: string },
) => { /* ... */ };
```

**Before this PR:**

The `obj` parameter node was flagged as "missing a comment" even though
its child `obj.hi` had a description extracted from `@param obj.hi`:

```json
{
  "missingComments": [
    { "id": "def-public.crazyFunction.$1", "label": "obj" }
  ]
}
// obj flagged even though its children are documented!
```

**After this PR:**

Parameter nodes (identified by `.$` in their `id`) are no longer flagged
when at least one child has a description:

```json
{
  "missingComments": []
}
// obj NOT flagged — child obj.hi has a description ✅
```

### Detection Logic

| Scenario | Flagged? | Reason |
|----------|----------|--------|
| No description, no children with descriptions | Yes | Genuinely
undocumented |
| No description, but child has description | **No** | Parent is
implicitly documented via children |
| Has own description | No | Directly documented |
| Non-parameter node without description | Yes | Not a parameter, normal
rules apply |

### Changes

- Refactor `missingComment` logic in `collectStatsForApi()` in
`stats.ts` to check for child descriptions on parameter nodes
- Un-skip the `does not flag destructured params when @param obj exists`
test
- Simplify the `does not flag destructured parameter children when
documented` test to assert the correct behavior directly

### Impact

- Reduces false positives in `missingComments` for plugins with
well-documented destructured parameters

Made with [Cursor](https://cursor.com)

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Tiago Costa <tiago.costa@elastic.co>

## Summary

Improves the `missingComments` detection in `kbn-docs-utils` to avoid
false positives on destructured parameter nodes. Previously, a parameter
like `obj` in `crazyFunction(obj: {hi: string})` was flagged as missing
a comment even when its children (`obj.hi`) were individually documented
via JSDoc.

> [!NOTE]
> This PR is a subset of elastic#247688
for ease of review.
>
> This PR was written with Cursor and `claude-4.5-opus-high`.

### Before / After Example

Given this JSDoc-annotated function:

```typescript
/**
 * Who would write such a complicated function?? Ewwww.
 *
 * @param {Object} obj A very crazy parameter.
 * @param {string} obj.hi Greeting on the obj.
 */
export const crazyFunction = (
  obj: { hi: string },
) => { /* ... */ };
```

**Before this PR:**

The `obj` parameter node was flagged as "missing a comment" even though
its child `obj.hi` had a description extracted from `@param obj.hi`:

```json
{
  "missingComments": [
    { "id": "def-public.crazyFunction.$1", "label": "obj" }
  ]
}
// obj flagged even though its children are documented!
```

**After this PR:**

Parameter nodes (identified by `.$` in their `id`) are no longer flagged
when at least one child has a description:

```json
{
  "missingComments": []
}
// obj NOT flagged — child obj.hi has a description ✅
```

### Detection Logic

| Scenario | Flagged? | Reason |
|----------|----------|--------|
| No description, no children with descriptions | Yes | Genuinely
undocumented |
| No description, but child has description | **No** | Parent is
implicitly documented via children |
| Has own description | No | Directly documented |
| Non-parameter node without description | Yes | Not a parameter, normal
rules apply |

### Changes

- Refactor `missingComment` logic in `collectStatsForApi()` in
`stats.ts` to check for child descriptions on parameter nodes
- Un-skip the `does not flag destructured params when @param obj exists`
test
- Simplify the `does not flag destructured parameter children when
documented` test to assert the correct behavior directly

### Impact

- Reduces false positives in `missingComments` for plugins with
well-documented destructured parameters

Made with [Cursor](https://cursor.com)

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Tiago Costa <tiago.costa@elastic.co>