docs: Document the core public API with JSDoc - #961
Merged
Conversation
Add eslint-plugin-jsdoc scoped to the export closure of src/index.ts. The jsdoc/require-jsdoc rule now flags every undocumented public export: 86 errors in handwritten modules and 1149 in generated code, to be resolved in subsequent commits. Internal modules (client, parse-options, api-error-types, version) are excluded by file scope rather than @internal tags. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XQyDWeGYQyCDEJ1rZ8J1iB
Add JSDoc to every public export reachable from the package entrypoint: options and their type guards, error classes and their properties, SeamHttpRequest, SeamPaginator, token predicates, and getOpenapiSchema. Also export ResolveActionAttemptOptions, SucceededActionAttempt, and FailedActionAttempt, which already appear in public type signatures (waitForActionAttempt and SeamActionAttemptFailedError) but were not re-exported, leaving TypeDoc unable to link them. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XQyDWeGYQyCDEJ1rZ8J1iB
Update the codegen templates to document every generated export: route class declarations, the client and defaults properties, static factory methods, sub-route getters, per-endpoint Parameters, Response, Request, and Options types, and the endpoint path types. Add a fallback description for resource types missing a description in the blueprint (DeviceProvider and SeamEvent). Expose routePath in the route and subroute layout contexts so templates can name the route they document. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XQyDWeGYQyCDEJ1rZ8J1iB
Resolve template conflicts by keeping both the JSDoc additions and the new request parameter validation from main, then regenerate all generated files with npm run generate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XQyDWeGYQyCDEJ1rZ8J1iB
Require JSDoc only on top-level exports, not class members or properties. Remove the generated docs on the endpoint Parameters, Response, Request, Options, and path types, and drop handwritten and template member docs that only repeat the member name or type, e.g., statusCode: 401. Member docs that carry real information remain, e.g., requestId, waitForActionAttempt, and the polling options. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XQyDWeGYQyCDEJ1rZ8J1iB
razor-x
marked this pull request as draft
August 18, 2026 23:31
razor-x
changed the title
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XQyDWeGYQyCDEJ1rZ8J1iB
Limit JSDoc to the concepts covered in the README: client options, authentication options and their type guards, action attempt resolution, pagination, requests, and errors. Revert all codegen template changes so generated code matches main, remove docs from the token predicates, auth helpers, error interceptor, and getOpenapiSchema, and narrow the lint rule to the core modules. Document the timeout, axiosOptions, and axiosRetryOptions client options from the README Advanced Usage section. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XQyDWeGYQyCDEJ1rZ8J1iB
razor-x
changed the title
razor-x
force-pushed
the
claude/public-api-docstrings-28gizu
branch
from
August 19, 2026 22:46
2a574d2 to
79d59a2
Compare
razor-x
marked this pull request as ready for review
August 19, 2026 22:53
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds JSDoc to the core client modules — the concepts covered in the README — with lint enforcement so coverage of those modules cannot regress. Generated code and codegen templates are untouched (identical to main); the blueprint already documents resources and endpoint methods.
Scope (all in
src/libcore modules):options.ts— everySeamHttpOptions*auth variant and type guard, including the guards' throwing behavior on conflicting auth options, and theendpointoption's env-var defaults.client.ts— the README Advanced Usage options:timeout(per-attempt, ms, 0 disables),axiosOptions,axiosRetryOptions. These surface on every public options interface.request-options.ts/resolve-action-attempt.ts—waitForActionAttempt,timeoutandpollingInterval(ms), theSeamActionAttempt*Errorclasses and guards.seam-http-request.ts—SeamHttpRequestis lazy/thenable and resolves action attempts on await;executevsfetchResponse.seam-paginator.ts—SeamPaginatorand its paging/iteration methods.seam-http-error.ts— theSeamHttpApiErrorfamily;requestIdis what you give Seam support.Enforcement:
eslint-plugin-jsdocwithjsdoc/require-jsdocon top-level exports of exactly those six modules (file list ineslint.config.ts). Members and properties are documented only where the docstring says something the signature can't — nothing forces astatusCode: 401-style comment.ResolveActionAttemptOptions,SucceededActionAttempt, andFailedActionAttemptare now re-exported from the entrypoint. They already appear in public type signatures (waitForActionAttemptandSeamActionAttemptFailedError) but were not exported, which left TypeDoc unable to link them. Happy to drop this if unwanted.Verification:
npm run lint,npm run typecheck,npm test(125 passed), andnpm run docs:build(0 errors) all pass.npm run generateoutput is unchanged from main.🤖 Generated with Claude Code
https://claude.ai/code/session_01XQyDWeGYQyCDEJ1rZ8J1iB