docs(core, client): extend docs, link modules (#226)

Author: 0x009922

packages/client/api-ws.ts

@@ -10,6 +10,12 @@ export class WebSocketAPI {
   public readonly toriiBaseURL: URL
   public readonly adapter: IsomorphicWebSocketAdapter
 
+  /**
+   * Create an instance.
+   * @param toriiBaseURL Torii base URL
+   * @param adapter A custom WebSocket adapter. Uses native by default.
+   * See the {@linkcode [web-socket]} module for more details.
+   */
   public constructor(toriiBaseURL: URL, adapter?: IsomorphicWebSocketAdapter) {
     this.toriiBaseURL = toriiBaseURL
     this.adapter = adapter ?? nativeWS

packages/client/web-socket/mod.ts

@@ -1,2 +1,30 @@
+/**
+ * Types and native implementation of a WebSocket transport.
+ *
+ * [The WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
+ * is not natively available everywhere. For when it is available, the built-in {@linkcode nativeWS}
+ * transport is used. For when it is not, consider using
+ * {@linkcode https://jsr.io/@iroha/client-web-socket-node|@iroha/client-web-socket-node} adapter or providing a custom
+ * one.
+ *
+ * A custom adapter could be passed to the {@linkcode [default].WebSocketAPI | WebSocketAPI} as well as to the
+ * {@linkcode [default].CreateClientParams | Client}.
+ *
+ * ### Note on Bun
+ *
+ * Although Bun provides "native" `WebSocket`, it's implementation is not spec-compliant (specifically, it uses Node's `Buffer`).
+ * Using `@iroha/client-web-socket-node` would work in this case.
+ *
+ * @example Using Node.js adapter
+ * ```ts
+ * import { WebSocketAPI } from '@iroha/client'
+ * import ws from '@iroha/client-web-socket-node'
+ *
+ * const api = new WebSocketAPI(new URL('http://localhost:8080'), ws)
+ * ```
+ *
+ * @module
+ */
+
 export * from './types.ts'
 export { default as nativeWS } from './native.ts'

packages/core/data-model/mod.ts

@@ -1,7 +1,8 @@
 /**
  * Iroha data model - types and codecs.
  *
- * It is based on the `schema.json` generated by Iroha. The schema itself is also available, see the `@iroha/core/data-model/schema` and `@iroha/core/data-model/schema-json` modules.
+ * It is based on the `schema.json` generated by Iroha. The schema itself is also available,
+ * see the {@linkcode [data-model/schema]} and {@linkcode [data-model/schema-json]} modules.
  *
  * ## Encoding
  *

packages/core/data-model/schema/json.ts

@@ -1,7 +1,7 @@
 /**
- * The Iroha's `schema.json` itself.
+ * The embedded `schema.json` used to generate this exact version of the package.
  *
- * Data model types are generated based on this schema. It could be used as a reference.
+ * Its types are described in the {@linkcode [data-model/schema]} module.
  *
  * @module
  */

packages/core/data-model/schema/mod.ts

@@ -1,5 +1,7 @@
 /**
- * Types describing Iroha's `schema.json` file.
+ * Types describing Iroha `schema.json` file.
+ *
+ * The embedded `schema.json` used to generate this exact version of the package is in the {@linkcode [data-model/schema-json]} module.
  *
  * @module
  */

packages/core/mod.ts

@@ -6,14 +6,14 @@
  *
  * This package consists of the following modules:
  *
- * - `data-model` - the data model
- * - `crypto` - cryptographic utilities
- * - `codec` - lower-level utilities to work with the codec
+ * - {@linkcode [data-model]} - the data model
+ * - {@linkcode [crypto]} - cryptographic utilities
+ * - {@linkcode [codec]} - lower-level utilities to work with the codec
  *
  * > [!IMPORTANT]
  * > This package includes a WebAssembly module to perform cryptographic operations in a way consistent with Iroha.
  * > It is a bit tricky to initialise uniformly across different environments, and **there could be compatibility issues**.
- * > See the `crypto` module for more details.
+ * > See the {@linkcode [crypto]} module for more details.
  *
  * ### Iroha Compatibility
  *
@@ -85,8 +85,6 @@
  * assertEquals(account.toString(), raw)
  * ```
  *
- * Note that this example requires WASM installation, because account id contains a public key.
- *
  * @module
  */