Add code reference links and backticks to JSDoc comments #1484
Conversation
|
@modelcontextprotocol/client
@modelcontextprotocol/server
@modelcontextprotocol/express
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
jonathanhefner
force-pushed
the
jsdoc-links-and-backticks
branch
from
067ff0a to
3e75363
Compare
| import type { ReadableWritablePair } from 'node:stream/web'; | ||
|
|
||
| import type { FetchLike, JSONRPCMessage, Transport } from '@modelcontextprotocol/core'; | ||
| // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Protocol used in JSDoc {@link} |
There was a problem hiding this comment.
Is there no other way than peppering the code with these linter overrides? If they're not being used in this file, is this the right place to document them?
There was a problem hiding this comment.
We can add explicit module paths for those links. I've added a commit to do that.
| * @param resultSchema - Zod schema for validating the result (defaults to {@linkcode CallToolResultSchema}) | ||
| * @param options - Optional request options (timeout, signal, task creation params, etc.) | ||
| * @returns AsyncGenerator that yields ResponseMessage objects | ||
| * @returns AsyncGenerator that yields {@linkcode ResponseMessage} objects |
There was a problem hiding this comment.
General question: how do these comments stay up to date? Is this checked as part of the CI pipeline that all these comments are correct and still linked to the right places?
There was a problem hiding this comment.
TypeDoc emits warnings for broken links, but we can turn those warnings into errors and check in CI: #1522
Replace plain text and backtick-quoted symbol references in JSDoc
comments with proper `{@linkcode}` tags for TypeDoc. This makes class
names, function names, and other symbols clickable in the generated API
documentation.
Also adds type-only imports with ESLint disable comments for symbols
that are only referenced in JSDoc `{@link}` tags.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Wrap code identifiers in backticks throughout JSDoc documentation for consistency. This includes parameter names, variable names, HTTP headers, OAuth grant types, URL paths, and string literals. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Use `index.` prefix in `{@linkcode}` tags to reference symbols via the
package index re-exports, eliminating the need for unused imports and
their eslint-disable comments.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
jonathanhefner
force-pushed
the
jsdoc-links-and-backticks
branch
from
3e75363 to
53a9bca
Compare
2 participants
This PR contains 2 somewhat overlapping commits which add the following to JSDoc comments across the code base:
{@linkcode}tags to cross-link code references, both for ease of reference and to catch docs drift (viapnpm run docs:check)The diff is somewhat large, but essentially uniform. The additional lines (404 lines vs 414 lines) are due to extra import statements and
// eslint-disable-next-line @typescript-eslint/no-unused-varscomments to allow TypeDoc to reference previously-unimported types in some{@linkcode}tags (i.e., the imports are used by TypeDoc, but eslint doesn't recognize that).