Add additional comments on type interfaces

packages/keyring/src/types.ts

@@ -5,13 +5,9 @@ import type { HexString } from '@polkadot/util/types';
 import type { EncryptedJson, Keypair, KeypairType, Prefix } from '@polkadot/util-crypto/types';
 
 export interface KeyringOptions {
-  /**
-   * @description The ss58Format to use for address encoding (defaults to 42)
-   */
+  /** The ss58Format to use for address encoding (defaults to 42) */
   ss58Format?: Prefix;
-  /**
-   * @description The type of keyring to create (defaults to ed25519)
-   */
+  /** The type of keyring to create (defaults to ed25519) */
   type?: KeypairType;
 }
 
@@ -76,9 +72,7 @@ export interface KeyringPair$Json extends EncryptedJson {
 }
 
 export interface SignOptions {
-  /**
-   * @description Create a MultiSignature-compatible output with an indicator type
-   **/
+  /** Create a MultiSignature-compatible output with an indicator type */
   withType?: boolean;
 }
 

packages/networks/src/types.ts

@@ -17,15 +17,22 @@ export type KnownSubstrate = RegistryEntry;
 export type KnownTestnet = Record<string, true>;
 
 export interface SubstrateNetwork extends KnownSubstrate {
+  /** The genesisHash for the chain */
   genesisHash: HexString[];
+  /** Does the chain has support for Ledger devices */
   hasLedgerSupport: boolean;
+  /** The IdentityIcon to use for the chain */
   icon: Icon;
+  /** Flag set when we don't include this chain */
   isIgnored: boolean;
+  /** Flag to indicate a testnet */
   isTestnet: boolean;
+  /** The Ledger-specific/required slip44 for the chain */
   slip44?: number | null;
 }
 
 export interface Network extends SubstrateNetwork {
+  /** The network assigned to this chain */
   network: string;
 }
 

packages/util-crypto/src/json/types.ts

@@ -6,12 +6,17 @@ export type EncryptedJsonVersion = '0' | '1' | '2' | '3';
 export type EncryptedJsonEncoding = 'none' | 'scrypt' | 'xsalsa20-poly1305';
 
 export interface EncryptedJsonDescriptor {
+  /** Descriptor for the content */
   content: string[];
+  /** The encoding (in current/latest versions this is always an array) */
   type: EncryptedJsonEncoding | EncryptedJsonEncoding[];
+  /** The version of encoding applied */
   version: EncryptedJsonVersion;
 }
 
 export interface EncryptedJson {
+  /** The encoded string */
   encoded: string;
+  /** The encoding used */
   encoding: EncryptedJsonDescriptor;
 }

packages/util-crypto/src/key/extractPath.ts

@@ -6,7 +6,7 @@ import { DeriveJunction } from './DeriveJunction.js';
 const RE_JUNCTION = /\/(\/?)([^/]+)/g;
 
 export interface ExtractResult {
-  parts: null | string[];
+  parts: string[] | null;
   path: DeriveJunction[];
 }
 

packages/util-crypto/src/key/extractSuri.ts

@@ -25,7 +25,7 @@ export function keyExtractSuri (suri: string): ExtractResult {
     throw new Error('Unable to match provided value to a secret URI');
   }
 
-  const [, phrase, , derivePath, , , password] = matches as string[];
+  const [, phrase, , derivePath, , , password] = matches;
   const { path } = keyExtractPath(derivePath);
 
   return {

packages/util-crypto/src/scrypt/defaults.ts

@@ -1,7 +1,9 @@
 // Copyright 2017-2023 @polkadot/util-crypto authors & contributors
 // SPDX-License-Identifier: Apache-2.0
 
-export const DEFAULT_PARAMS = {
+import type { ScryptParams } from './types.js';
+
+export const DEFAULT_PARAMS: ScryptParams = {
   N: 1 << 15,
   p: 1,
   r: 8

packages/util-crypto/src/scrypt/encode.ts

@@ -1,7 +1,7 @@
 // Copyright 2017-2023 @polkadot/util-crypto authors & contributors
 // SPDX-License-Identifier: Apache-2.0
 
-import type { Params } from './types.js';
+import type { ScryptParams } from './types.js';
 
 import { scrypt as scryptJs } from '@noble/hashes/scrypt';
 
@@ -12,7 +12,7 @@ import { randomAsU8a } from '../random/asU8a.js';
 import { DEFAULT_PARAMS } from './defaults.js';
 
 interface Result {
-  params: Params,
+  params: ScryptParams,
   password: Uint8Array;
   salt: Uint8Array;
 }

packages/util-crypto/src/scrypt/fromU8a.ts

@@ -1,15 +1,15 @@
 // Copyright 2017-2023 @polkadot/util-crypto authors & contributors
 // SPDX-License-Identifier: Apache-2.0
 
-import type { Params } from './types.js';
+import type { ScryptParams } from './types.js';
 
 import { u8aToBn } from '@polkadot/util';
 
 import { BN_LE_OPTS } from '../bn.js';
 import { DEFAULT_PARAMS } from './defaults.js';
 
 interface Result {
-  params: Params,
+  params: ScryptParams,
   salt: Uint8Array;
 }
 
@@ -19,9 +19,10 @@ export function scryptFromU8a (data: Uint8Array): Result {
   const p = u8aToBn(data.subarray(32 + 4, 32 + 8), BN_LE_OPTS).toNumber();
   const r = u8aToBn(data.subarray(32 + 8, 32 + 12), BN_LE_OPTS).toNumber();
 
-  // FIXME At this moment we assume these to be fixed params, this is not a great idea since we lose flexibility
-  // and updates for greater security. However we need some protection against carefully-crafted params that can
-  // eat up CPU since these are user inputs. So we need to get very clever here, but atm we only allow the defaults
+  // FIXME At this moment we assume these to be fixed params, this is not a great idea
+  // since we lose flexibility and updates for greater security. However we need some
+  // protection against carefully-crafted params that can eat up CPU since these are user
+  // inputs. So we need to get very clever here, but atm we only allow the defaults
   // and if no match, bail out
   if (N !== DEFAULT_PARAMS.N || p !== DEFAULT_PARAMS.p || r !== DEFAULT_PARAMS.r) {
     throw new Error('Invalid injected scrypt params found');

packages/util-crypto/src/scrypt/toU8a.ts

@@ -1,13 +1,13 @@
 // Copyright 2017-2023 @polkadot/util-crypto authors & contributors
 // SPDX-License-Identifier: Apache-2.0
 
-import type { Params } from './types.js';
+import type { ScryptParams } from './types.js';
 
 import { bnToU8a, u8aConcat } from '@polkadot/util';
 
 import { BN_LE_32_OPTS } from '../bn.js';
 
-export function scryptToU8a (salt: Uint8Array, { N, p, r }: Params): Uint8Array {
+export function scryptToU8a (salt: Uint8Array, { N, p, r }: ScryptParams): Uint8Array {
   return u8aConcat(
     salt,
     bnToU8a(N, BN_LE_32_OPTS),

packages/util-crypto/src/scrypt/types.ts

@@ -1,7 +1,8 @@
 // Copyright 2017-2023 @polkadot/util-crypto authors & contributors
 // SPDX-License-Identifier: Apache-2.0
 
-export interface Params {
+/** The params that control scrypt generation */
+export interface ScryptParams {
   N: number;
   p: number;
   r: number;

packages/util-crypto/src/types.ts

@@ -5,20 +5,29 @@ export * from './address/types.js';
 export * from './json/types.js';
 
 export interface Keypair {
+  /** The publicKey for this pair */
   publicKey: Uint8Array;
+  /** The secretKey for this pair */
   secretKey: Uint8Array;
 }
 
 export interface Seedpair {
+  /** The publicKey for this pair */
   publicKey: Uint8Array;
+  /** The seed used to construct the pair */
   seed: Uint8Array;
 }
 
+/** The supported types of pairs */
 export type KeypairType = 'ed25519' | 'sr25519' | 'ecdsa' | 'ethereum';
 
 export interface VerifyResult {
+  /** The detected crypto interface, or 'none' if not detected */
   crypto: 'none' | KeypairType;
+  /** The validity for this result, false if invalid */
   isValid: boolean;
+  /** Flag to indicate if the passed data was wrapped in <Bytes>...</Bytes> */
   isWrapped: boolean;
+  /** The extracted publicKey */
   publicKey: Uint8Array;
 }

packages/util/src/types.ts

@@ -5,6 +5,7 @@ import type { BN } from './bn/bn.js';
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+/** An interface that defines an actual JS class */
 export interface Class<T = any, A extends unknown[] = any[]> {
   prototype: T;
 
@@ -40,20 +41,14 @@ export interface Logger {
 }
 
 export interface ToBnOptions {
-  /**
-   * @description Convert in LE format
-   */
+  /** Convert in LE format */
   isLe?: boolean;
-  /**
-   * @description Number is signed, apply two's complement
-   */
+  /** Number is signed, apply two's complement */
   isNegative?: boolean;
 }
 
 export interface NumberOptions extends ToBnOptions {
-  /**
-   * @description Limit to the specified bitLength, despite input length
-   */
+  /** Limit to the specified bitLength, despite input length */
   bitLength?: number;
 }