chore: add jsdoc formatting and run format

carlosala · carlosala · commit 56b1ec44b0f4 · 2025-12-03T12:38:27.000+01:00
diff --git a/package.json b/package.json
@@ -12,9 +12,14 @@
   "prettier": {
     "printWidth": 80,
     "semi": false,
-    "trailingComma": "all"
+    "trailingComma": "all",
+    "jsdocExperimentalFormatCommentsWithoutTags": true,
+    "plugins": [
+      "@homer0/prettier-plugin-jsdoc"
+    ]
   },
   "devDependencies": {
+    "@homer0/prettier-plugin-jsdoc": "^10.0.1",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "prettier": "^3.7.1",
diff --git a/packages/common-utils/src/flattenResult.ts b/packages/common-utils/src/flattenResult.ts
@@ -10,8 +10,8 @@ export type Result<S = unknown, E = unknown> =
   | { success: false; value: E }
 
 /**
- * Flattens a nested Result<Result<Result<number>, ErrorA>, ErrorB>, ErrorC> into
- * { value: number } | null
+ * Flattens a nested Result<Result<Result<number>, ErrorA>, ErrorB>, ErrorC>
+ * into { value: number } | null.
  */
 export const flattenValues = <T>(v: T): { value: FlattenValues<T> } | null => {
   const result = flattenResult(v)
@@ -25,8 +25,8 @@ export type FlattenValues<T> =
       : T
 
 /**
- * Flattens a nested Result<Result<Result<number>, ErrorA>, ErrorB>, ErrorC> into
- * { error: ErrorA | ErrorB | ErrorC } | null
+ * Flattens a nested Result<Result<Result<number>, ErrorA>, ErrorB>, ErrorC>
+ * into { error: ErrorA | ErrorB | ErrorC } | null.
  */
 export const flattenErrors = <T>(v: T): { error: FlattenErrors<T> } | null => {
   const result = flattenResult(v)
@@ -42,8 +42,8 @@ export type FlattenErrors<T> =
       : never
 
 /**
- * Flattens a nested Result<Result<Result<number>, ErrorA>, ErrorB>, ErrorC> into
- * Result<number, ErrorA | ErrorB | ErrorC>
+ * Flattens a nested Result<Result<Result<number>, ErrorA>, ErrorB>, ErrorC>
+ * into Result<number, ErrorA | ErrorB | ErrorC>
  */
 export const flattenResult = <T>(v: T): FlattenResult<T> =>
   isResult(v)
diff --git a/packages/sdk-accounts/src/identity/descriptors.ts b/packages/sdk-accounts/src/identity/descriptors.ts
@@ -92,8 +92,9 @@ type IdentitySdkPallets = PalletsTypedef<
   {
     Identity: {
       /**
-       * Information that is pertinent to identify the entity behind an account. First item is the
-       * registration, second is the account's primary username.
+       * Information that is pertinent to identify the entity behind an account.
+       * First item is the registration, second is the account's primary
+       * username.
        *
        * TWOX-NOTE: OK ― `AccountId` is a secure hash.
        */ IdentityOf: StorageDescriptor<
@@ -103,8 +104,9 @@ type IdentitySdkPallets = PalletsTypedef<
         never
       >
       /**
-       * The super-identity of an alternative "sub" identity together with its name, within that
-       * context. If the account is not some other account's sub-identity, then just `None`.
+       * The super-identity of an alternative "sub" identity together with its
+       * name, within that context. If the account is not some other account's
+       * sub-identity, then just `None`.
        */
       SuperOf: StorageDescriptor<
         [Key: SS58String],
diff --git a/packages/sdk-accounts/src/linkedAccounts/descriptors.ts b/packages/sdk-accounts/src/linkedAccounts/descriptors.ts
@@ -11,8 +11,9 @@ type LinkedAccountsSdkPallets = PalletsTypedef<
   {
     Proxy: {
       /**
-       * The set of account proxies. Maps the account which has delegated to the accounts
-       * which are being delegated to, together with the amount held on deposit.
+       * The set of account proxies. Maps the account which has delegated to the
+       * accounts which are being delegated to, together with the amount held on
+       * deposit.
        */
       Proxies: StorageDescriptor<
         [Key: SS58String],
diff --git a/packages/sdk-accounts/src/linkedAccounts/multisigProviders/subscan-provider.ts b/packages/sdk-accounts/src/linkedAccounts/multisigProviders/subscan-provider.ts
@@ -4,10 +4,12 @@ import { MultisigProvider } from "../sdk-types"
 /**
  * Multisig provider for subscan API.
  *
- * See `throttleMultisigProvider` to throttle down requests to your API key limits.
+ * See `throttleMultisigProvider` to throttle down requests to your API key
+ * limits.
  *
- * @param chain See supported chains in https://support.subscan.io/doc-361776
- * @param subscanApiKey API key from subscan
+ * @param chain          See supported chains in
+ *                       https://support.subscan.io/doc-361776
+ * @param subscanApiKey  API key from subscan.
  */
 export function subscanProvider(
   chain: string,
diff --git a/packages/sdk-accounts/src/linkedAccounts/multisigProviders/throttle-provider.ts b/packages/sdk-accounts/src/linkedAccounts/multisigProviders/throttle-provider.ts
@@ -4,9 +4,10 @@ import { MultisigProvider } from "../sdk-types"
  * Throttles down the requests to the provider. By default it drops new requests
  * after the maximum concurrent requests has been reached.
  *
- * @param provider Multisig provider to throttle
- * @param maxConcurrent Maximum amount of concurrent requests
- * @param wait Queue requests instead of dropping them. It can cause backpressure.
+ * @param provider       Multisig provider to throttle.
+ * @param maxConcurrent  Maximum amount of concurrent requests.
+ * @param wait           Queue requests instead of dropping them. It can
+ *                       cause backpressure.
  */
 export function throttleMultisigProvider(
   provider: MultisigProvider,
diff --git a/packages/sdk-governance/src/bounties/descriptors.ts b/packages/sdk-governance/src/bounties/descriptors.ts
@@ -74,7 +74,8 @@ type BountiesSdkPallets<TOrigin> = PalletsTypedef<
     }
     Scheduler: {
       /**
-       * Items to be executed, indexed by the block number that they should be executed on.
+       * Items to be executed, indexed by the block number that they should be
+       * executed on.
        */
       Agenda: StorageDescriptor<
         [Key: number],
@@ -128,7 +129,7 @@ type BountiesSdkPallets<TOrigin> = PalletsTypedef<
   {
     Bounties: {
       /**
-       *New bounty proposal.
+       * New bounty proposal.
        */
       BountyProposed: PlainDescriptor<{
         index: number
diff --git a/packages/sdk-governance/src/referenda/sdk-types.ts b/packages/sdk-governance/src/referenda/sdk-types.ts
@@ -66,7 +66,7 @@ export interface ReferendaSdkConfig {
 }
 
 /**
- * threshold are in perbillion
+ * Threshold are in perbillion.
  */
 export interface TrackFunctionDetails {
   curve: ReferendaTypesCurve
diff --git a/packages/sdk-governance/src/voting/sdk-types.ts b/packages/sdk-governance/src/voting/sdk-types.ts
@@ -9,10 +9,14 @@ export type PollOutcome = {
 
 /**
  * Types:
- * - free: The funds locked by this vote will become free once the vote is removed.
- * - locked: The funds locked by this vote will become locked once the vote is removed.
- * - extends: Removing this vote will extend the duration of a pre-existing lock.
- * - extended: Removing this vote before its end will have it locked for the duration of the pre-existing lock.
+ * - free: The funds locked by this vote will become free once the vote is
+ * removed.
+ * - locked: The funds locked by this vote will become locked once the vote is
+ * removed.
+ * - extends: Removing this vote will extend the duration of a pre-existing
+ * lock.
+ * - extended: Removing this vote before its end will have it locked for the
+ * duration of the pre-existing lock.
  */
 export type VoteLock =
   | {
diff --git a/packages/sdk-ink/src/revive-sdk.ts b/packages/sdk-ink/src/revive-sdk.ts
@@ -13,7 +13,7 @@ import { defaultOptions, type InkSdkOptions, type ReviveSdk } from "./sdk-types"
 import { ss58ToEthereum } from "./util"
 
 /**
- * @deprecated use `createInkSdk(client)` instead
+ * @deprecated Use `createInkSdk(client)` instead.
  */
 export const createReviveSdk = <
   T extends ReviveSdkTypedApi,
diff --git a/packages/sdk-ink/src/sdk-types.ts b/packages/sdk-ink/src/sdk-types.ts
@@ -55,7 +55,7 @@ export interface InkV5Sdk<
 }
 
 /**
- * @deprecated Old interface, will be removed in a future version
+ * @deprecated Old interface, will be removed in a future version.
  */
 export interface ReviveSdk<
   T extends ReviveSdkTypedApi,
@@ -109,12 +109,14 @@ export interface GetContract {
 
 export interface InkSdkOptions {
   /**
-   * Target the latest block instead of the finalized block for any query or dry-run operation.
+   * Target the latest block instead of the finalized block for any query or
+   * dry-run operation.
    *
-   * This makes it possible to have quicker updates, but be mindful that the data returned might become
-   * invalid at any point, e.g. a contract that apparently was successfully deployed might suddenly
-   * disappear, just to reappear a few seconds later, or maybe never? Be really mindful
-   * you can get inconsistencies.
+   * This makes it possible to have quicker updates, but be mindful that the
+   * data returned might become invalid at any point, e.g. a contract that
+   * apparently was successfully deployed might suddenly disappear, just to
+   * reappear a few seconds later, or maybe never? Be really mindful you can get
+   * inconsistencies.
    */
   atBest: boolean
 }
diff --git a/packages/sdk-staking/src/sdk-types.ts b/packages/sdk-staking/src/sdk-types.ts
@@ -99,18 +99,18 @@ export interface StakingSdk {
   /**
    * Get validator rewards for a specific era.
    *
-   * @param address Validator address to check.
-   * @param era Optional era, defaults to ActiveEra.
+   * @param address  Validator address to check.
+   * @param era      Optional era, defaults to ActiveEra.
    */
   getValidatorRewards: (
     address: SS58String,
     era?: number,
   ) => Promise<ValidatorRewards | null>
 
   /**
-   * Gets the active validators info for a specific era
+   * Gets the active validators info for a specific era.
    *
-   * @param era Optional era, defaults to ActiveEra.
+   * @param era  Optional era, defaults to ActiveEra.
    */
   getEraValidators: (era?: number) => Promise<{
     totalRewards: bigint
@@ -124,19 +124,19 @@ export interface StakingSdk {
   /**
    * Gets the list of nominators that were active for a specific era
    *
-   * Expensive operation: will fetch (and cache) every nominator
+   * Expensive operation: will fetch (and cache) every nominator.
    *
-   * @param era Optional era, defaults to ActiveEra.
+   * @param era  Optional era, defaults to ActiveEra.
    */
   getActiveNominators: (era?: number) => Promise<Array<SS58String>>
 
   /**
    * Get nominator status for specific era.
    *
-   * Expensive operation: will fetch (and cache) every nominator
+   * Expensive operation: will fetch (and cache) every nominator.
    *
-   * @param address Nominator address to check.
-   * @param era Optional era, defaults to ActiveEra.
+   * @param address  Nominator address to check.
+   * @param era      Optional era, defaults to ActiveEra.
    */
   getNominatorActiveValidators: (
     address: SS58String,
@@ -146,10 +146,10 @@ export interface StakingSdk {
   /**
    * Get nominator rewards for specific era.
    *
-   * Expensive operation: will fetch (and cache) every nominator
+   * Expensive operation: will fetch (and cache) every nominator.
    *
-   * @param address Nominator address to check.
-   * @param era Optional era, defaults to ActiveEra.
+   * @param address  Nominator address to check.
+   * @param era      Optional era, defaults to ActiveEra.
    */
   getNominatorRewards: (
     address: SS58String,
@@ -172,7 +172,8 @@ export interface StakingSdk {
   /**
    * Unbonds `amount` tokens from the nomination pool of `member`.
    *
-   * Will throw an error if the member is not in a nomination pool, or if it doesn't have a large enough bond.
+   * Will throw an error if the member is not in a nomination pool, or if it
+   * doesn't have a large enough bond.
    */
   unbondNominationPool: (member: SS58String, amount: bigint) => AsyncTransaction
   getNominationPools: () => Promise<NominationPool[]>
diff --git a/packages/sdk-statement/src/statement-sdk.ts b/packages/sdk-statement/src/statement-sdk.ts
@@ -7,10 +7,12 @@ import { filterDecKey, filterTopics } from "./utils"
 /**
  * Create statement sdk.
  *
- * @param {RequestFn} req Takes a req-res function, which accepts Statement RPC
- *                        calls. This can be `client._request` (from `polkadot-api`)
- *                        client, `client.request` (from `@polkadot-api/substrate-client`)
- *                        or any other crafted by the consumer.
+ * @param {RequestFn} req  Takes a req-res function, which accepts Statement RPC
+ *                         calls. This can be `client._request` (from
+ *                         `polkadot-api`)
+ *                         client, `client.request` (from
+ *                         `@polkadot-api/substrate-client`)
+ *                         or any other crafted by the consumer.
  */
 export const createStatementSdk = (req: RequestFn) => {
   const api = getApi(req)
@@ -24,9 +26,11 @@ export const createStatementSdk = (req: RequestFn) => {
 
     /**
      * Get statements from store.
-     * dest: `Binary` means to get all statements with that specific `decryptionKey` set.
-     *       `null` means to get all statements with no `decryptionKey` set.
-     *       `undefined` (or unset) means to get all statements disregarding `decryptionKey`.
+     * dest: `Binary` means to get all statements with that specific
+     * `decryptionKey` set.
+     * `null` means to get all statements with no `decryptionKey` set.
+     * `undefined` (or unset) means to get all statements disregarding
+     * `decryptionKey`.
      */
     getStatements: async ({
       dest,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -66,7 +66,7 @@ export interface ReferendaSdkConfig {`
`66`	`66`	`}`
`67`	`67`
`68`	`68`	`/**`
`69`		`- * threshold are in perbillion`
	`69`	`+ * Threshold are in perbillion.`
`70`	`70`	`*/`
`71`	`71`	`export interface TrackFunctionDetails {`
`72`	`72`	`curve: ReferendaTypesCurve`