Conversation
There was a problem hiding this comment.
Pull request overview
This PR focuses on improving generated API documentation by adjusting the TypeDoc configuration and refining JSDoc so TypeDoc produces more complete/usable output.
Changes:
- Updated
typedoc.jsonoptions and addedexternalSymbolLinkMappingsfor external symbols referenced via{@link ...}. - Added/normalized JSDoc
@returns(with explicit types) on several documented APIs. - Updated README links for
JobType/JobStatus/JobResultdocumentation.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| typedoc.json | Adjusts TypeDoc output behavior and introduces external symbol link mappings. |
| src/tasks/key-generation/key-generation.dto.ts | Adds JSDoc for validator methods to improve generated docs. |
| src/jobs/jobs.types.ts | Removes a stray comment marker near JobResult typing docs. |
| src/common/config/config.service.ts | Adds explicit JSDoc @returns {type} for config getters. |
| README.md | Changes documentation links for job-related types/enums. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| /** | ||
| * @param {number} threshold - The threshold value to validate. | ||
| * @param {ValidationArguments} args - Context containing the parent DTO. | ||
| * @returns {boolean} `true` if threshold is within participants or not yet | ||
| * parseable. | ||
| */ | ||
| validate(threshold: number, { object }: ValidationArguments): boolean { | ||
| const dto: KeyGenerationRequestDto = object as KeyGenerationRequestDto; | ||
| // If `participants` hasn't been parsed yet, defer to its own validator. | ||
| return dto.participants === undefined || threshold <= dto.participants; |
There was a problem hiding this comment.
The new JSDoc for validate documents a @param {ValidationArguments} args, but the signature destructures the second argument ({ object }: ValidationArguments) and there is no args parameter. This makes the generated docs misleading; either rename the parameter in the signature or update the JSDoc to match the actual parameter name/shape (and consider clarifying that the early-true case is when participants is still undefined).
| "\"crypto\".timingSafeEqual": "#" | ||
| }, | ||
| "@nestjs/common": { | ||
| "UnauthorizedException": "#" | ||
| }, | ||
| "@grpc/grpc-js": { | ||
| "Metadata": "#" |
There was a problem hiding this comment.
externalSymbolLinkMappings currently maps external symbols to "#", which produces non-useful/broken links in the rendered docs (everything points to the top of the current page). If the goal is to make {@link ...} references clickable, map these symbols to the appropriate external documentation URLs (e.g., Node.js/NestJS/gRPC API docs) or omit the mapping and tolerate the unresolved-link warnings.
| "\"crypto\".timingSafeEqual": "#" | |
| }, | |
| "@nestjs/common": { | |
| "UnauthorizedException": "#" | |
| }, | |
| "@grpc/grpc-js": { | |
| "Metadata": "#" | |
| "\"crypto\".timingSafeEqual": "https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b" | |
| }, | |
| "@nestjs/common": { | |
| "UnauthorizedException": "https://www.jsdocs.io/package/@nestjs/common#UnauthorizedException" | |
| }, | |
| "@grpc/grpc-js": { | |
| "Metadata": "https://www.jsdocs.io/package/@grpc/grpc-js#Metadata" |
| * `JobType`: see [documentation](https://shreeed-app.github.io/multi-party-computation-controller-api/enums/jobs_jobs.types.JobType.html) for possible enum values. | ||
| * `JobStatus`: see [documentation](https://shreeed-app.github.io/multi-party-computation-controller-api/enums/jobs_jobs.types.JobStatus.html) for possible enum values. | ||
| * `JobResult`: see [documentation](https://shreeed-app.github.io/multi-party-computation-controller-api/types/jobs_jobs.types.JobResult.html) for possible result structures. |
There was a problem hiding this comment.
The README now hard-codes documentation links to https://shreeed-app.github.io/.... This will be incorrect for forks, non-master previews, or local documentation builds (where docs/ exists). Consider keeping relative links (e.g., ./docs/...) or providing both a relative link and a hosted GitHub Pages link so the README remains portable.
| * `JobType`: see [documentation](https://shreeed-app.github.io/multi-party-computation-controller-api/enums/jobs_jobs.types.JobType.html) for possible enum values. | |
| * `JobStatus`: see [documentation](https://shreeed-app.github.io/multi-party-computation-controller-api/enums/jobs_jobs.types.JobStatus.html) for possible enum values. | |
| * `JobResult`: see [documentation](https://shreeed-app.github.io/multi-party-computation-controller-api/types/jobs_jobs.types.JobResult.html) for possible result structures. | |
| * `JobType`: see [documentation](./docs/enums/jobs_jobs.types.JobType.html) for possible enum values. | |
| * `JobStatus`: see [documentation](./docs/enums/jobs_jobs.types.JobStatus.html) for possible enum values. | |
| * `JobResult`: see [documentation](./docs/types/jobs_jobs.types.JobResult.html) for possible result structures. |
No description provided.