docs: JSDoc quality pass across @tonconnect/sdk, ui, ui-react, protocol#552
Draft
ArkadiyStena wants to merge 41 commits into
Draft
docs: JSDoc quality pass across @tonconnect/sdk, ui, ui-react, protocol#552ArkadiyStena wants to merge 41 commits into
ArkadiyStena wants to merge 41 commits into
Conversation
|
@ArkadiyStena is attempting to deploy a commit to the TOP Team on Vercel. A member of the Team first needs to authorize it. |
ArkadiyStena
changed the title
TypeDoc and IDE tooltips attach a leading /** … */ block to the next exported symbol. Each of the six files under utils/uuid/ opens with the MIT license as a /** doc comment, so generators pick up the license text as the summary of UUIDTypes, UUIDv7, etc. Switch the opening to /* (non-doc) on all six files so the license remains in the source but stops leaking into the generated reference. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The class previously inherited 'Thrown when wallet can't get manifest by passed manifestUrl.' from ManifestNotFoundError, which sends readers to the wrong cause. The error is actually raised from onWalletConnected when checkRequiredWalletFeatures(device.features, walletsRequiredFeatures) returns false — i.e. the wallet does not advertise the features the dApp requires. Rewrite the summary to match the runtime behaviour and point at the relevant constructor option. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- ton-connect.ts and ton-connect.interface.ts: 'Disconnect form thw connected wallet' -> 'Disconnect from the connected wallet'. - models/dapp/dapp-metadata.ts: 'overwise' -> 'otherwise'. - errors/unknown.error.ts: 'Unhanded unknown error' -> 'Unhandled unknown error'. The @default rewrite in dapp-metadata.ts is left for a follow-up commit to keep the diff focused. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The public TonConnect.signData and TonConnect.signMessage implementations carry no JSDoc, and ITonConnect.signData on the interface is undocumented as well. Without source-level docs, TypeDoc, IDE tooltips, and tsc quick-info show empty hovers for these methods. Document each method with its purpose, parameters, return shape, and the named error classes it can throw (WalletNotConnectedError, WalletNotSupportFeatureError, WalletWrongNetworkError, UserRejectsError, BadRequestError, TonConnectError). The throws set was confirmed against parsers/sign-data-parser.ts, parsers/sign-message-parser.ts, utils/feature-support.ts, and the wrong-network branch in ton-connect.ts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Protocol behaviours and SDK invariants are normative statements, so they read more naturally in the present tense. Update the cases the audit doc called out, plus a handful of others surfaced while sweeping: - onStatusChange callback/errorsHandler descriptions: 'will be called' -> 'fires'. - setConnectionNetwork: 'the SDK will throw an error and abort connection' -> 'the SDK throws an error and aborts the connection'. - DappMetadata.url description: 'Will be used as ... Will be used to open ...' rewritten as one present-tense sentence. - WalletInfoBase.tondns: 'Will be used in the protocol later' replaced with a description of what the field is and that it is reserved. - TonConnectOptions.manifestUrl: 'that will be displayed' / 'will be taken' -> present tense. - initializeWalletConnect: 'A second call will throw' -> 'throws'. - WalletConnect metadata types: 'will be displayed to users' -> 'is shown to users'. The @returns clauses still containing future-tense throw descriptions (sendTransaction, signMessage) and the @param options lines combined with the '(optional)' prefix are left for the @returns-split commit and the throat-clearing commit so each diff stays focused. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TypeDoc renders @returns and @throws in separate sections. The trailing 'If user rejects transaction, method will throw...' lines stapled onto @returns blocks land in the wrong section, so downstream readers see return-value documentation that talks about errors and an empty Throws panel. Move the user-rejects clause from @returns into a dedicated @throws {UserRejectsError} line on: - TonConnect.sendTransaction (ton-connect.ts). - ITonConnect.sendTransaction (ton-connect.interface.ts). - ITonConnect.signMessage (ton-connect.interface.ts). The wider @throws expansion across the full public API arrives in the next commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Before this commit a grep for '@throws' across packages/sdk/src returned zero matches, so TypeDoc rendered an empty Throws section for every public method even though each can fail with one or more named error classes. Add @throws blocks on both the TonConnect class and the ITonConnect interface for: - getWallets: FetchWalletsError. - connect: WalletAlreadyConnectedError, TonConnectError. - sendTransaction: WalletNotConnectedError, WalletNotSupportFeatureError, WalletWrongNetworkError, UserRejectsError, BadRequestError, UnknownAppError, TonConnectError. - signMessage (interface): same set as sendTransaction. - disconnect: WalletNotConnectedError, TonConnectError. - setConnectionNetwork: TonConnectError. signData and signMessage on the class already received their @throws sets when the missing JSDoc commit landed. The throw sets were derived from the actual code paths in ton-connect.ts (validation, abort, wrong-network), utils/feature-support.ts (WalletNotSupportFeatureError variants), wallets-list-manager.ts (FetchWalletsError), and parsers/{send-transaction,sign-data,sign-message}-parser.ts (UserRejectsError, BadRequestError, UnknownAppError, TonConnectError via parseAndThrowError). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TypeDoc reads @default as a literal value and renders it in the 'Default value' cell of the property table. The DappMetadata fields all embedded conditional prose into their @default tag, so the rendered table read things like '`document.title` if exists, "Unknown dapp" otherwise' or '`window.location.origin` if exists, otherwise (if not explicitly specified) an error will be thrown.' Drop the @default tag on each DappMetadata field and move the conditional behaviour into the prose description. The bare `<link>` inside the icon description is wrapped in backticks so renderers do not treat it as an HTML tag. The url field's error path now names the specific error class (DappMetadataError) and the condition that triggers it. Also drop the stray '@' on its own line inside the walletsListSource JSDoc in models/ton-connect-options.ts — it parsed as an empty tag and produced a warning in TypeDoc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
JSDoc text in models/ and the TonConnect class mixed 'Dapp' / 'dapp', 'Url', and 'nodeJS' / 'NodeJS' even though the protocol and TON ecosystem documentation consistently use 'dApp', 'URL', and 'Node.js'. TypeDoc renders the source text verbatim, so the rendered reference and IDE tooltips reproduce the inconsistency. Normalise these forms throughout JSDoc comments and one user-facing error message: - DappMetadata.name/icon/url: 'Dapp' -> 'dApp', 'dapp' -> 'dApp', literal default 'Unknown dapp' -> 'Unknown dApp'. - TonConnectOptions.manifestUrl: 'Url' -> 'URL', 'Dapp' -> 'dApp'. - TonConnectOptions.storage: 'nodeJS' -> 'Node.js'. - WalletInfoBase.imageUrl, WalletInfoRemote.bridgeUrl: 'Url' -> 'URL'. - WalletInfoCurrentlyEmbedded: 'dapp' -> 'dApp'. - WalletConnectionSourceHTTP.bridgeUrl: 'Url' -> 'URL'. - TonConnect/ITonConnect.pauseConnection: 'NodeJS' -> 'Node.js'. - TonConnect constructor error message: 'Dapp tonconnect-manifest.json' -> 'dApp tonconnect-manifest.json'. Identifiers in TypeScript code, the analytics 'dapp-sdk' subsystem string, and similar literals are left untouched. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ructor Sixteen of seventeen error subclasses carry their own class-level JSDoc; WalletWrongNetworkError was the lone exception, so its rendered reference page showed no summary at all. Add a summary describing when the error is thrown and what fields the `cause` carries. Separately, every subclass uses `constructor(...args: ConstructorParameters<typeof TonConnectError>)` and forwards to `super(...args)`. TypeDoc then inherits the parent constructor's JSDoc — which was absent, so it fell back to the class summary 'Base class for TonConnect errors' for every subclass's constructor section. Give the base constructor its own JSDoc that describes the actual contract (the `[TON_CONNECT_SDK_ERROR]` prefix behaviour, the subclass-typed `cause`), so subclass docs inherit something meaningful. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TypeScript already marks parameter optionality via '?', so the '(optional) ' prefix in front of every optional @param description was duplicate signal. The DappMetadata.url field also led with 'It is recommended to pass url without closing slash...' instead of stating the rule. Rewrite the affected @param lines on both TonConnect and ITonConnect as imperative descriptions of what each option does (and incidentally fix the leftover 'will be called' future-tense fragments that lived inside them, plus the meaningless 'options (optional) options' line on ITonConnect.connect). Rewrite the dApp URL recommendation as a direct imperative. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The four address helpers — toUserFriendlyAddress, isValidUserFriendlyAddress, isValidRawAddress, and parseUserFriendlyAddress — share a similar one-line summary, so it is non-obvious at the call site which one a reader should reach for. Each helper now carries an @example block showing realistic input and the shape of the returned value, including the EQ/UQ/0Q/kQ prefix families for toUserFriendlyAddress and the masterchain (-1) variant for isValidRawAddress. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Verifier pass over the @throws blocks introduced in the JSDoc quality pass found two mismatches against the runtime code paths: - getWallets: the @throws {FetchWalletsError} line was incorrect. WalletsListManager.fetchWalletsListFromSource constructs and throws FetchWalletsError inside a try block whose catch (wallets-list-manager.ts line 137) swallows the error and falls back to FALLBACK_WALLETS_LIST, so the public TonConnect.getWallets path never surfaces it. Replace the inaccurate @throws with a prose note describing the fallback. - signData (TonConnect class and ITonConnect interface) and signMessage (TonConnect class): the parsers map UNKNOWN_APP_ERROR -> UnknownAppError alongside USER_REJECTS_ERROR and BAD_REQUEST_ERROR (see parsers/sign-data-parser.ts line 19 and parsers/sign-message-parser.ts line 20), so UnknownAppError is reachable on these methods. Add the missing @throws {UnknownAppError} lines so the rendered Throws section matches the actual error map and matches ITonConnect.signMessage, which already documented it. Verified with `tsc --project packages/sdk/tsconfig.json --noEmit` (exit 0) and `eslint packages/sdk/src` (exit 0). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The address @example blocks added in the previous documentation pass asserted base64 outputs that did not match what the function actually returns. Verified against the published @tonconnect/sdk lib/cjs/index.cjs bundle by invoking toUserFriendlyAddress directly: > toUserFriendlyAddress('0:b97df5ef066ef7b80fc23dd9e2a02d6c620a76c4b81f3923ed8e94e2ae00f53b') 'UQC5ffXvBm73uA_CPdnioC1sYgp2xLgfOSPtjpTirgD1Ozvy' > toUserFriendlyAddress('0:b97df5ef066ef7b80fc23dd9e2a02d6c620a76c4b81f3923ed8e94e2ae00f53b', true) '0QC5ffXvBm73uA_CPdnioC1sYgp2xLgfOSPtjpTirgD1O4B4' Replace the previous strings (`UQC5ffXvBm73uA_CPdniqgLWxiCnbEuB85I-2OlOKuAPU3kF` and `0QC5ffXvBm73uA_CPdniqgLWxiCnbEuB85I-2OlOKuAPU0SB`) with the actual output. The same correction is applied to the matching strings in the isValidUserFriendlyAddress, isValidRawAddress, and parseUserFriendlyAddress examples so the four blocks stay consistent and round-trip cleanly. The raw hex input and the documented `parseUserFriendlyAddress` return shape (wc / hex / testOnly / isBounceable) were already correct and are preserved. Verified with `tsc --project packages/sdk/tsconfig.json --noEmit` (exit 0) and `eslint packages/sdk/src` (exit 0). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TypeDoc 0.27's JSDoc lexer strips the `{ClassName}` portion from
`@throws {ClassName} description` entirely — `tag.content` only carries
the description text, with no reference to the class. Downstream
TypeDoc-based renderers therefore lose the most important piece of
information in an `@throws` line: which error class to `catch`.
`@throws {@link ClassName} description` keeps the class name as an
inline `@link` content part with a resolved `target`, which renderers
can extract and turn into a navigable link. This is the TSDoc-blessed
form for the same intent.
Apply the rewrite to every `@throws` line on TonConnect and
ITonConnect — 52 lines across ton-connect.ts and ton-connect.interface.ts.
No prose changes, no type changes, tsc --noEmit still exits 0.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The embedded-request header described the value as "URL-encoded" rather than Base64-URL JSON, and the `f` field comment claimed it defaults to the connected account — the spec actually says the wallet prompts the user when `from` is omitted. Update the structured-item header to match reality too (most fields are camelCase; `extra_currency` is the only snake_case key that survives from the original spec). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…pers @tonconnect/protocol is the normative reference for the TonConnect wire format. Most of its types and enums had no JSDoc at all, so TypeDoc and IDE tooltips show empty hovers and the rendered reference page was mostly bare. Document: - The CHAIN enum and ChainId type (mainnet '-239', testnet '-3', and the custom global_id escape hatch). - The AppRequest / AppMessage / WalletMessage / WalletResponse families (request/response envelopes that bridge messages travel in). - ConnectRequest, ConnectItem, and disconnect/sign-message request shapes. - DeviceInfo, Feature, RpcMethod (the device-features discriminated union readers actually need to reason about feature gating). - KeyPair, SessionCrypto (the crypto primitives session establishment uses). - Base64 and binary utility helpers with @example blocks. - The web-api helpers. All entries describe the wire-level meaning and cross-link sibling types via {@link}. No runtime behaviour or wire-format string literal changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…d SessionCrypto constructor Document that decodeEmbeddedRequestParam throws URIError on malformed percent-encoding and SyntaxError on invalid JSON, and that the SessionCrypto constructor throws Error when passed an odd-length hex string via hexToByteArray. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous @throws annotation claimed URIError covers "malformed percent-encoding" — but the input is Base64-URL, not percent-encoded, so percent-encoding is never involved. Trace the actual failure paths: - Invalid Base64 → nacl.decodeBase64's validateBase64 throws TypeError ('invalid encoding'). This case was undocumented. - Decoded bytes that don't form valid UTF-8 → decodeURIComponent inside nacl.encodeUTF8 throws URIError ('URI malformed'). This is the real trigger, not malformed percent-encoding of the input. - Invalid JSON → JSON.parse throws SyntaxError (unchanged). Switch the tags to TSDoc inline-link form ({@link TypeError} etc.) so the api-reference renderer keeps the class name (TypeDoc drops the JSDoc curly-brace type from parsed content). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TypeDoc drops the JSDoc @throws {ClassName} curly-brace type from the parsed content entirely. The api-reference renderer reads the class name from a leading {@link ClassName} inline tag instead, so emit that form even for built-in error classes (Error here) to keep rendering consistent with future error-class throws. Affects SessionCrypto.{constructor,decrypt} and binary.{splitToUint8Arrays, hexToByteArray}. No behavioural change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
IDE tooltips and the auto-generated reference for `@tonconnect/ui` ship these typos verbatim, so a reader looking at `tonConnectUI.wallet` sees "Curren connected wallet" and `setConnectRequestParameters` documents calling "multiply times". The TWA `twaReturnUrl` description ended with a dangling `if).` that truncated the sentence; restore it to `if set)`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Protocol and UI invariants ("the SDK will throw", "the loader will
appear", "metadata will be displayed") read as predictions in the
generated reference. Present tense states what the code does today,
which is what callers need to know. Targets TonConnectUI public
methods, the option models, `useOpenedNotifications`, and the
`openDeeplinkWithFallback` Safari caveat. Deprecation lines that
genuinely announce a future removal are left alone.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The manifest field documents itself as `Url to the [manifest]…with the Dapp metadata`, so IDE tooltips and the generated reference both show the inconsistent forms. `sendOpenTelegramLink` also throws `Url protocol is not supported` / `Url host is not supported`, which surfaces at the call site of every redirect. Aligns with the upstream sdk pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TypeDoc renders the contents of @default verbatim in the 'Default value' cell. Stray trailing periods (`@default true.`) become part of the rendered literal and look like typos. Strip them, and replace prose values with the actual identifier (e.g. `BrowserEventDispatcher.` -> `\`new BrowserEventDispatcher()\``, `div#tc-widget-root.` -> `'tc-widget-root'` to match the field's documented value). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Add JSDoc to static getWallets(), walletsRequiredFeatures getter, walletsPreferredFeatures getter, and constructor - Add @param/@returns to onStatusChange, disconnect, sendTransaction, signData, signMessage, connectWallet - Add @throws {@link TonConnectUIError} to constructor, uiOptions setter, sendTransaction, signData, signMessage, connectWallet - Fix connectWallet: replace plain-text throws annotation with TSDoc {@link} form; move throw out of @return into @throws - Fix uiOptions setter summary (imperative voice) - Fix onStatusChange summary (present tense, imperative @return verb) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add one-line summaries to THEME enum, Theme type, BorderRadius, ColorsSet, PartialColorsSet, Locales, Loadable, LoadableLoading, LoadableReady, WalletOpenMethod, WalletInfoWithOpenMethod, WalletInfoRemoteWithOpenMethod, WalletInfoWalletConnect, and ConnectedWallet. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`TonConnectUIError` is thrown across `@tonconnect/ui` (modal lifecycle, deeplink helpers, configuration checks), not only by the `TonConnectUI` class — fix the class summary accordingly and mirror the `TonConnectError` constructor description from the sdk pass so the message-prefix invariant is documented at the UI layer too. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Constructor: it applies the initial UI options on the last line of the body (`this.uiOptions = mergeOptions(...)`), so it can also throw the `buttonRootId` check from the `uiOptions` setter — add the matching `@throws` clause. - `sendTransaction`/`signData`/`signMessage`: the bridge-flow wrapper re-throws SDK errors verbatim (`if (e instanceof TonConnectError) throw e`), so the original `TonConnectError` subclasses (`WalletWrongNetworkError`, `WalletNotSupportFeatureError`, `UserRejectsError`, `BadRequestError`, `UnknownAppError`, …) propagate through the UI layer. Document this so callers know they can still narrow on the SDK error hierarchy. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The old summary read "Thrown when either <TonConnectProvider> not added to the top of the tags tree, either there is an attempt using TonConnect UI hook or <TonConnectButton> inside <TonConnectProvider>". Two issues: the trailing clause says "inside" but the error fires when a hook or the button is used *outside* the provider, and the doubled "either / either" is ungrammatical (and the component name in the prose is also off — the provider is `TonConnectUIProvider`, not `TonConnectProvider`). Replace with a single present-tense sentence that names the runtime condition correctly and points the reader at the fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hook behaviours and provider semantics are normative statements about what the API does right now, so present tense reads more naturally and matches the sdk pass. - useTonWallet / useTonAddress: 'hook will return null' / 'will return empty string' -> 'Returns null when no wallet is connected' / 'Returns an empty string when no wallet is connected'. - TonConnectUIProviderPropsWithManifest.manifestUrl: 'metadata that will be displayed' / 'manifest ... will be taken' -> present tense. - TonConnectUIProviderPropsWithInstance.instance: 'it will be stored ... and reused' rewritten as 'A custom instance is stored ... and reused'. - TonConnectUIProviderPropsBase.widgetRootId: 'will be added and used' -> 'the library appends ... and uses it'. The `@default true.` trailing period and the `Dapp` proper-noun casing on the same provider lines are left for their own commits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TypeDoc renders @default as a literal value cell. A trailing period appears verbatim inside the cell, so `@default true.` becomes the literal "true." in the rendered reference and the IDE quick-info. Strip the periods from `restoreConnection` and `widgetRootId`. The other two @default lines in the file (`@default system`, `@default true`) already match this style. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`TonConnectUIProviderPropsWithManifest.manifestUrl`'s description used 'Url' (should be 'URL') and 'Dapp' (should be 'dApp'). The sdk pass applied the same normalisation across `packages/sdk/src/` — keep the two packages consistent so IDE tooltips and the generated reference read the same way regardless of which side of the wrapper the user is looking at. The identifier `manifestUrl` is unchanged — it is a public API name, not prose. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Both error classes in this package use the `constructor(...args: ConstructorParameters<typeof Error>)` pattern and forward to `super(...args)`. Without their own JSDoc, TypeDoc walks the prototype chain, and because the parent `TonConnectUIError` in @tonconnect/ui has no constructor JSDoc either, the inherited summary on each subclass's constructor section ends up empty (or, when a grand-parent does have one, misattributed). Add a short hand-written constructor JSDoc on each so: - `TonConnectUIReactError` documents that arguments forward through the standard ES `Error` constructor and that subclasses are the intended public surface. - `TonConnectProviderNotSetError` notes that the library raises this internally from `checkProvider` and consumers normally only catch it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mirror the sdk pass: - TonConnectButton: 'It is recommended to place it in the top right corner of your app.' -> 'Place it in the top right corner of your app.' State the rule (WRITING-GUIDE §1.2 / §17). - TonConnectButton @param className/style: drop `[ ]` brackets around the param name. TypeScript already encodes optionality via the prop type; the brackets in JSDoc just duplicate that and render as literal square brackets in the IDE tooltip. - TonConnectUIProvider @param options: same, drop `[options]` -> `options`. - useTonAddress @param userFriendly: drop `[userFriendly=true]` -> `userFriendly`. Move the default note into the description so the IDE tooltip doesn't double up the default value cell with the bracket-syntax default. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Every public hook can throw `TonConnectProviderNotSetError`:
`useTonConnectUI` calls `checkProvider(tonConnectUI)`, which throws when
the React context is `null` (i.e. no `<TonConnectUIProvider>` ancestor),
and the four other hooks all call `useTonConnectUI` internally. The
behaviour was undocumented — `@throws` returned zero hits across
`packages/ui-react/src/`.
Add a single `@throws` line per hook. `useTonConnectUI` notes the
server-side carve-out explicitly because that's where the check is
gated — on the server the hook returns a no-op `[null, () => {}]`
tuple rather than throwing. The other hooks inherit the same
client-side condition transitively, so the shorter form is enough.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hook JSDoc is what new ui-react users actually read in their IDE tooltip the first time they import a hook. A one-line summary leaves two pieces of context unstated: (a) when the hook causes a re-render (useTonWallet subscribes to onStatusChange, useTonConnectModal to onModalStateChange, useIsConnectionRestored awaits a one-shot promise), and (b) what a realistic call site looks like. Add an @example showing a small React component for each hook, plus a short paragraph above the @throws line covering the re-render behaviour and any side effects of the returned tuple: - useTonConnectUI: tuple is stable across renders; setOptions merges into uiOptions. Example shows openModal and a setOptions call. - useTonWallet: subscribes to onStatusChange. Example shows the null/connected branch. - useTonAddress: documents the userFriendly branch (UQ user-friendly vs raw 0:hex form) and the testnet flag handling. Example shows both forms side by side. - useTonConnectModal: subscribes to onModalStateChange; documents the null state. Example shows toggling between open/close based on state.status. - useIsConnectionRestored: documents the false -> true transition. Example shows gating UI behind the restored flag. The examples don't assert specific outputs (these are hooks, not value-returning utilities) — they show realistic component shapes that type-check against the public API. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
TypeDoc strips the JSDoc `@throws {ClassName} description` curly-brace
type from the parsed content, so the error class name was being lost in
the rendered reference. The renderer in
`tools/api-reference/src/render.ts` documents the same constraint and
expects authors to use the TSDoc inline-link form
`@throws {@link ClassName} description` (see the comment at
`parseThrowsTag`); only then can it pick up the class name as the
`@link` text on `content[0]`.
Convert the five hook `@throws` lines to use `{@link
TonConnectProviderNotSetError}`. No description changes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…hide TonConnectUIContext Move the JSDoc comment for TonConnectButton and TonConnectUIProvider to the post-memo() binding so TypeDoc and downstream tooling surface the existing component documentation. Hide TonConnectUIContext from public docs via @internal — it is a React.Context implementation detail; consumers use TonConnectUIProvider, not the bare context. No runtime behaviour change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Six small follow-ups surfaced when generating the API reference against the integrated JSDoc pass. None of them change runtime behaviour. 1. `TonConnectUIError` (ui) and `TonConnectUIReactError` (ui-react) now declare their constructors explicitly: `constructor(message?: string, options?: ErrorOptions)` instead of `constructor(...args: ConstructorParameters<typeof Error>)`. The forwarded-tuple form prevented TypeDoc from binding the `@param message` / `@param options` JSDoc to real parameters, so the rendered `**Constructor:**` block on each base class showed only the blurb, never the param table. 2. `TonConnectButton` and `TonConnectUIProvider` JSDoc rewritten to describe the component and point at the props interface; the `@param className` / `@param style` / `@param children` / `@param options` lines were authored against an outdated signature and TypeDoc could not bind them either. Props now carry their own JSDoc on `TonConnectButtonProps.className`/`.style` and on `TonConnectUIProviderProps.children`. The stray `@constructor` JSDoc tags are dropped (TypeDoc reports them as unknown tags). 3. `TonConnect.connect` JSDoc no longer carries `@param request` — the non-deprecated overload accepts the request as `options.request`, so the standalone tag never bound to a parameter. The `options` description now spells out where to pass `ton_proof`. 4. `useTonAddress` `@param userFriendly` no longer ends with `Defaults to \`true\`.` — the renderer auto-appends the default from the signature, so the JSDoc author and the renderer were both saying it, producing `Defaults to \`true\`. Defaults to \`true\`.` in the rendered cell. 5. Same shape on `SingleWalletModalManager.close` / `WalletsModalManager.close`: drop the redundant "Defaults to `'action-cancelled'`" from the @param text. The signature default speaks for itself. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ArkadiyStena
force-pushed
the
docs/jsdoc-quality
branch
from
2b8b8c5 to
08257e0
Compare
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
1 participant
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.
Summary
JSDoc quality pass across four TonConnect packages —
@tonconnect/sdk,@tonconnect/ui,@tonconnect/ui-react,@tonconnect/protocol— motivated by issues a downstream consumer (the auto-generated API reference fordocs.ton.org/ecosystem/ton-connect) ran into when generating reference pages with TypeDoc.The pass is split into per-package, per-category atomic commits so each can be reviewed (or dropped) independently. After each package's initial pass, a second sub-agent re-verified the claims against actual code paths and the upstream spec, applied a small number of corrections, and signed off. No runtime behaviour changes — JSDoc, comments, and a handful of user-facing message-string casings only.
tsc --noEmitexits 0 on all four packages at HEAD.What landed per package
@tonconnect/sdk(16 commits)Twelve original commits (one per audit category) plus four follow-up corrections from a self-review and a verifier pass:
WalletMissingRequiredFeaturesErrordescription corrected, typos, missing JSDoc onsignData/signMessage, future-tense → present,@returns/@throwssplit, full@throwscoverage,@defaulttamed, casing normalised,WalletWrongNetworkErrorsummary + base constructor JSDoc, throat-clearing removed,@exampleblocks on address utilities.@throws {FetchWalletsError}ongetWallets(caller swallows + falls back), added missing@throws {UnknownAppError}tosignData/signMessage, replaced fabricatedtoUserFriendlyAddress@exampleoutputs with real computed values, migrated all@throwsfrom JSDoc curly-brace form@throws {X}to TSDoc inline-link form@throws {@link X}(TypeDoc strips the curly-brace form before downstream renderers see it).@tonconnect/protocol(5 commits)eparam,ffield default, structured-item casing) verified against the upstream spec atbridge.md/requests-responses.md.CHAIN,Feature,RpcMethod), the request/response envelope families, and crypto primitives (KeyPair,SessionCrypto); cross-linked siblings via{@link}.@throwscoverage ondecodeEmbeddedRequestParamandSessionCryptoconstructor; reviewer corrected thedecodeEmbeddedRequestParamset (real causes areTypeError/URIError/SyntaxError, not "malformed percent-encoding"). All@throwsuse TSDoc{@link X}form.@returns/@throwssplit,@defaultprose) — confirmed by exhaustive grep.@tonconnect/ui(9 commits)TonConnectUIand option models; future-tense → present; casing (URL, dApp);@defaultliterals (trailing dots, prose values).TonConnectUImethod, getter, setter, and the constructor; full@throwscoverage in TSDoc{@link X}form, including the bridge-flow re-throw paths that propagate SDK errors (WalletWrongNetworkError,UserRejectsError,BadRequestError,UnknownAppError).TonConnectUIError's class summary and constructor JSDoc so subclasses inherit a meaningful description (same pattern asTonConnectErrorin the sdk pass).THEME,BorderRadius,Loadable,Locales,ConnectedWallet,ColorsSet).@tonconnect/ui-react(9 commits)TonConnectProviderNotSetErrordescription to match its actual throw point (thecheckProvidergate inuseTonConnectUI).@defaulttrailing dots, casing, error subclass constructor JSDoc, throat-clearing.@throws {@link TonConnectProviderNotSetError}coverage on all five public hooks (useTonAddress,useTonConnectUI,useTonWallet,useIsConnectionRestored,useTonConnectModal); reviewer migrated the form from JSDoc curly-brace to TSDoc inline-link.@exampleblocks (with re-render notes) on all five hooks. No fabricated return values.Risk
Documentation-only. Two user-visible strings change (already noted in earlier revisions of this PR): the corrected
WalletMissingRequiredFeaturesErrordescription, and the'Dapp tonconnect-manifest.json must be specified ...'→'dApp tonconnect-manifest.json ...'casing fix in the SDK constructor error. Both prefixes ([TON_CONNECT_SDK_ERROR] DappMetadataError) remain unchanged because they're built fromthis.constructor.name.No runtime behaviour, no public API shape, no type changes, no wire-format literal changes.
Test plan
tsc --project packages/sdk/tsconfig.json --noEmitexits 0tsc --project packages/protocol/tsconfig.json --noEmitexits 0tsc --project packages/ui/tsconfig.json --noEmitexits 0tsc --project packages/ui-react/tsconfig.json --noEmitexits 0eslint packages/<pkg>/srcclean for each touched package@throws {ClassName}reachable: verified against the source paths (parsers' error-code maps, feature-support checks, validation calls, wrong-network branches, parserparseAndThrowError)@throwsuses TSDoc{@link X}form (TypeDoc strips the JSDoc{X}form)toUserFriendlyAddress@exampleoutputs computed against the real implementation; round-trip verified throughparseUserFriendlyAddress.references/ton-connect-spec/{bridge,requests-responses}.mdObservations left for follow-up (not addressed in this PR)
parseUserFriendlyAddress,isValidUserFriendlyAddress,isValidRawAddresscarry new@exampleblocks but are not re-exported frompackages/sdk/src/index.ts(onlytoUserFriendlyAddressis). The examples still help in-source readers and IDE hovers but won't appear in public TypeDoc output. Adding them to the public surface is a behaviour-bearing change.WalletNotFoundErrorinpackages/ui/src/errors/configuration/is exported but never re-exported througherrors/index.tsand has zero usages — effectively dead code. Worth a cleanup pass, separately.SingleWalletModalManager.openinpackages/ui/src/managers/still has a bare-text@throws TonConnectUIError— the class isn't part of the package's public surface so it's strictly out of this PR's stated scope, but worth aligning in a follow-up.ConnectEvent,ConnectEventSuccess,TonAddressItemReply,TonProofItemReplySuccess, theCONNECT_EVENT_ERROR_CODESenum,RpcResponsesmap entries). Out of scope of this pass — flagging for completeness.Opened as a draft — happy to split, squash, reword, or drop individual commits per maintainer preference.
🤖 Generated with Claude Code