Skip to content

docs(source): two source comments about a mis-aimed navigationContributions[].group are incomplete against what #14920 shipped #16507

Description

@huangyiirene

Found while implementing #14925 (the describe() half). Filing rather than fixing there: #14925's scope is the one describe() string and the spec regeneration family it pulls, and one of these two spots is in another package entirely.

Both are source comments — neither reaches a generated artifact. Verified: git grep for the JSDoc sentence below matches packages/spec/src/ui/app.zod.ts only, while the sibling describe() string matched the two generated reference pages as well, so the two strings do have different reaches and the negative is a real reading rather than a silent miss.

1. packages/spec/src/ui/app.zod.ts, the NavigationContributionSchema JSDoc (around :739)

 * tree by **target group id + priority** (lower priority applied first,
 * mirroring object extender ordering). When `group` is omitted the items are
 * appended at the app's top level. Contributed items keep the normal nav

This is the same incompleteness #14925 fixed one screen down on the describe(): it documents the omitted case and says nothing about group being present and naming no group the target app declares — the case an author cannot detect from their own source, because the target app belongs to another package. As of #14925 the describe() immediately below now names that case; the JSDoc above it still does not, so the two halves of the same key's authoring-time documentation disagree.

2. examples/app-multi-package/src/packages/orders/index.ts:47

 * (`nav_contribution_group_missing`, at `warn`), and `os build` reports the
 * same finding at compile time. This fixture is where that is measured

Names only os build. What shipped in #14920 computes the finding in both commands: findNavGroupDiagnostics is imported by packages/cli/src/commands/compile.ts:49 and packages/cli/src/commands/validate.ts:43, and both fold it into the same warnings key (compile.ts:202, validate.ts:148). content/docs/ui/setup-app.mdx already carries the corrected form ("os build and os validate"), so this comment is the odd one out.

Suggested fix

Prose only, both spots, no behaviour: add the mis-aimed case to the JSDoc in the spelling content/docs/ui/setup-app.mdx and the describe() now use, and add os validate to the example's comment. Neither string feeds a generated artifact, so this pulls no regeneration family.

Not in #14925 because

The bounded-in-place-fix test fails on the no-new-verification-surface condition: examples/app-multi-package is a separate package with its own build and test lane, so folding it in would widen that PR's affected set beyond the spec regeneration family it was sized for. The JSDoc half is in the same file but is a judgement about wording rather than a mechanical repair, and #14925's dispatch scoped it to the describe() explicitly.

Filed unassigned. Confirmed not already filed: a targeted search over this repo returned only #14925 itself (the positive control that proved the search could return a hit) and four unrelated docs-generation cards.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions