docs: Document the entire public API with JSDoc - #961
Open
razor-x wants to merge 5 commits into
Open
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
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.
Documents every top-level export reachable from the package entrypoint and adds lint enforcement so coverage cannot regress.
Doc policy: a docstring is required on every exported class, function, and type — but not on class members or properties, and never where it would only restate the name or signature. Member docs exist only where they carry real information (e.g.,
requestIdis what you give Seam support,SeamHttpRequest.executevsfetchResponsesemantics,waitForActionAttempt, polling option units).Commits by concern:
feat: Require JSDoc on the public API surface— Addseslint-plugin-jsdocwithjsdoc/require-jsdocscoped to the export closure ofsrc/index.ts(explicit file list ineslint.config.ts). Internal modules (client.ts,parse-options.ts,api-error-types.ts,version.ts,request-parameters.ts) are excluded by file scope, so no@internaltags were needed. At this commit the rule flagged 86 handwritten and 1,149 generated undocumented exports, proving it works.docs: Document the handwritten public API— JSDoc for all handwritten public exports: everySeamHttpOptions*variant and type guard (including their throwing behavior), the error classes,SeamHttpRequest(its thenable/waitForActionAttemptbehavior),SeamPaginator, the token predicates, andgetOpenapiSchema.docs: Generate JSDoc for all public exports— Template-level docs for the generated route classes, static factory methods, sub-route getters (mapping property → API route), and a fallback description for resources with no blueprint description (DeviceProvider,SeamEvent).Merge origin/main— Template conflicts resolved by keeping both the docs and the new request parameter validation, then regenerating.docs: Remove docstrings that restate their signatures— Applies the doc policy above: drops the generated per-endpoint*Parameters/*Response/*Request/*Optionsand path-type docs and all tautological member docs (e.g.,statusCode: 401), and relaxes the lint rule to top-level exports only. Generated route files additionally do not require docs on exported types, since those are self-describing.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(104 passed), andnpm run docs:build(0 errors) all pass.npm run generateis idempotent against these templates.🤖 Generated with Claude Code
https://claude.ai/code/session_01XQyDWeGYQyCDEJ1rZ8J1iB