Skip to content

docs: complete and enforce public API documentation coverage - #741

Draft
IzumiSy wants to merge 3 commits into
mainfrom
docs/complete-public-api-coverage
Draft

IzumiSy wants to merge 3 commits into
mainfrom
docs/complete-public-api-coverage

Conversation

@IzumiSy

@IzumiSy IzumiSy commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Motivation

The documentation checker reported 117 uncovered public exports, even though many already had explanations in existing reference pages. Coverage was advisory-only, so newly exported APIs could continue to ship without an associated documentation source.

Reviewing those pages also exposed outdated API descriptions and copyable examples that violated the Rules of Hooks or treated a failed HTTP response as a successful permission check. Closing the coverage gap should make the references accurate, not only remove warnings.

Design Decision

Reuse existing reference pages

Bind first-party exports to canonical pages through their resolved source files, and use explicit claims for external re-exports. Add missing explanations and cross-links within those pages rather than introducing exclusions, duplicating every shared-source family across individual hook pages, or creating new pages solely to satisfy coverage.

Enforce coverage after closing the gap

Enable the existing coverage gate only after every root-entrypoint export is tracked. This makes future uncovered exports fail docs:check without changing runtime behavior or the public API.

Summary

  • Track all 326 root-entrypoint exports, reducing uncovered exports from 117 to zero with no exclusions or new documentation pages.
  • Correct authentication, typed routing, module/resource, error-boundary, tooltip, and Hook usage examples to match the current APIs.
  • Fix permission-check examples to inspect HTTP status or an explicit permission flag instead of relying on Response truthiness.
  • Explain the remaining context, command-palette, local AI-tool, sidebar, shared UI-type, and date-helper APIs.
  • Regenerate documentation and the manifest, add patch changesets, and make documentation coverage mandatory.

@github-actions

Copy link
Copy Markdown
Contributor

Code Metrics Report

main (923933d) #741 (31af6d0) +/-
Coverage 62.9% 62.9% 0.0%
Test Execution Time 4m3s 4m23s +20s
Details
  |                     | main (923933d) | #741 (31af6d0) | +/-  |
  |---------------------|----------------|----------------|------|
  | Coverage            |          62.9% |          62.9% | 0.0% |
  |   Files             |            294 |            294 |    0 |
  |   Lines             |          13483 |          13483 |    0 |
  |   Covered           |           8485 |           8485 |    0 |
- | Test Execution Time |           4m3s |          4m23s | +20s |

Reported by octocov

@IzumiSy

IzumiSy commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

@copilot resolve the merge conflicts in this pull request

…api-coverage

# Conflicts:
#	docs-manifest.json

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot AI commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

@copilot resolve the merge conflicts in this pull request

Merged main and resolved the docs-manifest.json conflict by regenerating it from the merged sources. Merge commit: 7bae90bb.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the documentation and coverage-gate updates.

No open issues 🎉

What changed in this PR

This PR connects AppShell’s public exports to canonical documentation pages and makes documentation coverage mandatory, without changing runtime behavior or the public API.

Changes:

  • Add source bindings and external re-export claims to cover all 326 root-entrypoint exports.
  • Correct API descriptions and examples, including Hook usage, authentication, routing, permission checks, and tooltip placement.
  • Regenerate documentation and its manifest, enable the coverage gate, and add patch changesets.
File Description
docs/​concepts/​modules-and-resources.md Clarify page props, module requirements, and guards.
docs/​concepts/​file-based-routing.md Document PageComponent and correct module setup.
docs/​concepts/​authentication.md Explain client types and component-scoped cleanup.
docs/​components/​tooltip.md Document the preferred position API.
docs/​components/​sidebar-layout.md Explain content-container props and path segments.
docs/​components/​select.md Correct controlled and async Select examples.
docs/​components/​menu.md Document shared PositionProps.
docs/​components/​date-picker.md Explain date types, parsing, and timezone handling.
docs/​components/​command-palette.md Document programmatic opening and prefix behavior.
docs/​components/​badge.md Include additional public badge types.
docs/​components/​app-shell.md Correct module, error-boundary, and augmentation examples.
docs/​api/​use-route-error.md Correct error narrowing and module examples.
docs/​api/​use-register-command-palette-actions.md Clarify registration and callback updates.
docs/​api/​use-page-meta.md Move breadcrumb Hook calls into child components.
docs/​api/​use-auth.md Update login options and provider setup.
docs/​api/​use-app-shell.md Explain context APIs and route-parameter registration.
docs/​api/​use-app-shell-data.md Use component-scoped context-data examples.
docs/​api/​use-app-shell-config.md Use a component-scoped configuration example.
docs/​api/​use-ai-chat.md Explain local tools, validation, and cancellation.
docs/​api/​guards/​redirect-to.md Complete required module options.
docs/​api/​guards/​pass.md Clarify component-less route behavior.
docs/​api/​guards/​overview.md Correct permission checks and guard examples.
docs/​api/​guards/​hidden.md Check HTTP status before permitting access.
docs/​api/​define-resource.md Correct resource types, metadata, and examples.
docs/​api/​define-module.md Correct required options and grouping behavior.
docs/​api/​create-typed-paths.md Describe the current typed-path factory API.
docs-src/​hooks/​use-toast.docs.outline.md Bind toast documentation to its source.
docs-src/​hooks/​use-theme.docs.outline.md Bind theme documentation to its source.
docs-src/​hooks/​use-route-error.docs.outline.md Author corrected error-handling examples.
docs-src/​hooks/​use-register-command-palette-actions.docs.outline.md Author registration behavior corrections.
docs-src/​hooks/​use-page-meta.docs.outline.md Add source binding and fix breadcrumb Hook usage.
docs-src/​hooks/​use-override-breadcrumb.docs.outline.md Bind breadcrumb documentation to its source.
docs-src/​hooks/​use-auth.docs.outline.md Author current authentication examples.
docs-src/​hooks/​use-app-shell.docs.outline.md Bind context exports and explain registration.
docs-src/​hooks/​use-app-shell-data.docs.outline.md Correct context-data Hook examples.
docs-src/​hooks/​use-app-shell-config.docs.outline.md Correct configuration Hook usage.
docs-src/​hooks/​use-ai-chat.docs.outline.md Bind AI exports and explain local tools.
docs-src/​hooks/​guards/​redirect-to.docs.outline.md Complete the redirect example’s module options.
docs-src/​hooks/​guards/​pass.docs.outline.md Clarify what passing guards permits.
docs-src/​hooks/​guards/​overview.docs.outline.md Author safer permission checks and guard guidance.
docs-src/​hooks/​guards/​hidden.docs.outline.md Replace response truthiness with status checks.
docs-src/​hooks/​define-resource.docs.outline.md Align resource documentation with public signatures.
docs-src/​hooks/​define-module.docs.outline.md Align module documentation with current behavior.
docs-src/​hooks/​create-typed-paths.docs.outline.md Bind and rewrite the typed-path reference.
docs-src/​hooks/​create-ai-gateway-client.docs.outline.md Bind AI Gateway client exports.
docs-src/​concepts/​routing-navigation.docs.outline.md Claim external routing re-exports.
docs-src/​concepts/​modules-and-resources.docs.outline.md Bind resource exports and clarify their contracts.
docs-src/​concepts/​file-based-routing.docs.outline.md Bind routing types and explain PageComponent.
docs-src/​concepts/​authentication.docs.outline.md Bind authentication exports and claim AuthClient.
docs-src/​components/​tooltip.docs.outline.md Author placement API guidance.
docs-src/​components/​tooltip.docs.examples.tsx Use position in the runnable example.
docs-src/​components/​sidebar-layout.docs.outline.md Bind sidebar helpers and explain shared APIs.
docs-src/​components/​select.docs.outline.md Bind shared item types and correct examples.
docs-src/​components/​menu.docs.outline.md Bind and explain PositionProps.
docs-src/​components/​global-header-layout.docs.outline.md Include global-header source coverage.
docs-src/​components/​form.docs.outline.md Include Field and Fieldset source coverage.
docs-src/​components/​default-sidebar.docs.outline.md Include sidebar primitive exports.
docs-src/​components/​date-picker.docs.outline.md Bind calendar exports and claim date helpers.
docs-src/​components/​command-palette.docs.outline.md Bind context exports and explain opening behavior.
docs-src/​components/​badge.docs.outline.md Include badge-list type coverage.
docs-src/​components/​app-shell.docs.outline.md Author corrected AppShell setup examples.
docs-manifest.json Refresh symbol coverage and generated-content hashes.
docs-kit.config.json Make documentation coverage mandatory.
.changeset/​tidy-public-api-docs.md Record documentation and coverage improvements.
.changeset/​clear-breadcrumb-hooks.md Record the breadcrumb Hook example correction.

Review effort: Balanced

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants