Apply JSDoc comments onto PortableRegistry (#5443)

packages/types/src/metadata/PortableRegistry/PortableRegistry.ts

@@ -94,7 +94,7 @@ const RESERVED = [
 // Remove these from all paths at index 1
 const PATH_RM_INDEX_1 = ['generic', 'misc', 'pallet', 'traits', 'types'];
 
-/** @internal */
+/** @internal Converts a Text[] into string[] (used as part of definitions) */
 function sanitizeDocs (docs: Text[]): string[] {
   const result = new Array<string>(docs.length);
 
@@ -105,7 +105,7 @@ function sanitizeDocs (docs: Text[]): string[] {
   return result;
 }
 
-/** @internal */
+/** @internal Split a namespace with :: into individual parts */
 function splitNamespace (values: string[]): string[][] {
   const result = new Array<string[]>(values.length);
 
@@ -116,7 +116,7 @@ function splitNamespace (values: string[]): string[][] {
   return result;
 }
 
-/** @internal */
+/** @internal Match a namespace based on parts (alongside wildcards) */
 function matchParts (first: string[], second: (string | Text)[]): boolean {
   return first.length === second.length && first.every((a, index) => {
     const b = second[index].toString();
@@ -151,8 +151,7 @@ function matchParts (first: string[], second: (string | Text)[]): boolean {
   });
 }
 
-// check if the path matches the PATHS_ALIAS (with wildcards)
-/** @internal */
+/** @internal check if the path matches the PATHS_ALIAS (with wildcards) */
 function getAliasPath ({ def, path }: SiType): string | null {
   // specific logic for weights - we only override when non-complex struct
   if (path.join('::') === 'sp_weights::weight_v2::Weight' && def.isComposite && def.asComposite.fields.length !== 1) {
@@ -165,7 +164,7 @@ function getAliasPath ({ def, path }: SiType): string | null {
     : null;
 }
 
-/** @internal */
+/** @internal Converts a type name into a JS-API compatible name */
 function extractNameFlat (portable: PortableType[], lookupIndex: number, params: SiTypeParameter[], path: AnyString[], isInternal = false): Extract | null {
   const count = path.length;
 
@@ -219,12 +218,12 @@ function extractNameFlat (portable: PortableType[], lookupIndex: number, params:
   return { lookupIndex, name, params };
 }
 
-/** @internal */
+/** @internal Alias for extractNameFlat with PortableType as a last parameter */
 function extractName (portable: PortableType[], lookupIndex: number, { type: { params, path } }: PortableType): Extract | null {
   return extractNameFlat(portable, lookupIndex, params, path);
 }
 
-/** @internal */
+/** @internal Check for dupes from a specific index onwards */
 function nextDupeMatches (name: string, startAt: number, names: Extract[]): Extract[] {
   const result = [names[startAt]];
 
@@ -239,7 +238,7 @@ function nextDupeMatches (name: string, startAt: number, names: Extract[]): Extr
   return result;
 }
 
-/** @internal */
+/** @internal Checks to see if a type is a full duplicate (with all params matching) */
 function rewriteDupes (input: ExtractBase[], rewrite: Record<number, string>): boolean {
   const count = input.length;
 
@@ -266,7 +265,7 @@ function rewriteDupes (input: ExtractBase[], rewrite: Record<number, string>): b
   return true;
 }
 
-/** @internal */
+/** @internal Find duplicates and adjust the names based on parameters */
 function removeDupeNames (lookup: PortableRegistry, portable: PortableType[], names: Extract[]): Extract[] {
   const rewrite: Record<number, string> = {};
 
@@ -385,7 +384,7 @@ function removeDupeNames (lookup: PortableRegistry, portable: PortableType[], na
     }));
 }
 
-/** @internal */
+/** @internal Detect on-chain types (AccountId/Signature) as set as the default */
 function registerTypes (lookup: PortableRegistry, lookups: Record<string, string>, names: Record<number, string>, params: Record<string, SiTypeParameter[]>): void {
   // Register the types we extracted
   lookup.registry.register(lookups);
@@ -424,9 +423,10 @@ function registerTypes (lookup: PortableRegistry, lookups: Record<string, string
   }
 }
 
-// this extracts aliases based on what we know the runtime config looks like in a
-// Substrate chain. Specifically we want to have access to the Call and Event params
-/** @internal */
+/**
+ * @internal Extracts aliases based on what we know the runtime config looks like in a
+ * Substrate chain. Specifically we want to have access to the Call and Event params
+ **/
 function extractAliases (params: Record<string, SiTypeParameter[]>, isContract?: boolean): Record<number, string> {
   const hasParams = Object.keys(params).some((k) => !k.startsWith('Pallet'));
   const alias: Record<number, string> = {};
@@ -452,7 +452,7 @@ function extractAliases (params: Record<string, SiTypeParameter[]>, isContract?:
   return alias;
 }
 
-/** @internal */
+/** @internal Extracts all the intreresting type information for this registry */
 function extractTypeInfo (lookup: PortableRegistry, portable: PortableType[]): TypeInfo {
   const nameInfo: Extract[] = [];
   const types: Record<number, PortableType> = {};
@@ -513,6 +513,9 @@ export class PortableRegistry extends Struct implements ILookup {
     // console.log('PortableRegistry', `${(performance.now() - timeStart).toFixed(2)}ms`)
   }
 
+  /**
+   * @description Returns all the available type names for this chain
+   **/
   public get names (): string[] {
     return Object.values(this.#names).sort();
   }
@@ -524,6 +527,9 @@ export class PortableRegistry extends Struct implements ILookup {
     return this.getT('types');
   }
 
+  /**
+   * @description Register all available types into the registry (generally for internal usage)
+   */
   public register (): void {
     registerTypes(this, this.#lookups, this.#names, this.#params);
   }
@@ -594,6 +600,9 @@ export class PortableRegistry extends Struct implements ILookup {
     return this.#typeDefs[lookupIndex];
   }
 
+  /**
+   * @description For a specific field, perform adjustments to not have built-in conflicts
+   */
   public sanitizeField (name: Option<Text>): [string | null, string | null] {
     let nameField: string | null = null;
     let nameOrig: string | null = null;
@@ -613,6 +622,7 @@ export class PortableRegistry extends Struct implements ILookup {
     return [nameField, nameOrig];
   }
 
+  /** @internal Creates a TypeDef based on an internal lookupId */
   #createSiDef (lookupId: SiLookupTypeId): TypeDef {
     const typeDef = this.getTypeDef(lookupId);
     const lookupIndex = lookupId.toNumber();
@@ -629,6 +639,7 @@ export class PortableRegistry extends Struct implements ILookup {
       : typeDef;
   }
 
+  /** @internal Converts a lookupId input to the actual lookup index */
   #getLookupId (lookupId: SiLookupTypeId | string | number): number {
     if (isString(lookupId)) {
       if (!this.registry.isLookupType(lookupId)) {
@@ -643,6 +654,7 @@ export class PortableRegistry extends Struct implements ILookup {
     return lookupId.toNumber();
   }
 
+  /** @internal Converts a type into a TypeDef for Codec usage */
   #extract (type: SiType, lookupIndex: number): TypeDef {
     const namespace = type.path.join('::');
     let typeDef: TypeDef;
@@ -675,6 +687,7 @@ export class PortableRegistry extends Struct implements ILookup {
     }, typeDef);
   }
 
+  /** @internal Extracts a ScaleInfo Array into TypeDef.VecFixed */
   #extractArray (_: number, { len, type }: SiTypeDefArray): TypeDef {
     const length = len.toNumber();
 
@@ -689,6 +702,7 @@ export class PortableRegistry extends Struct implements ILookup {
     });
   }
 
+  /** @internal Extracts a ScaleInfo BitSequence into TypeDef.Plain */
   #extractBitSequence (_: number, { bitOrderType, bitStoreType }: SiTypeDefBitSequence): TypeDef {
     // With the v3 of scale-info this swapped around, but obviously the decoder cannot determine
     // the order. With that in-mind, we apply a detection for LSb0/Msb and set accordingly
@@ -713,6 +727,7 @@ export class PortableRegistry extends Struct implements ILookup {
     };
   }
 
+  /** @internal Extracts a ScaleInfo Compact into TypeDef.Compact */
   #extractCompact (_: number, { type }: SiTypeDefCompact): TypeDef {
     return withTypeString(this.registry, {
       info: TypeDefInfo.Compact,
@@ -720,6 +735,7 @@ export class PortableRegistry extends Struct implements ILookup {
     });
   }
 
+  /** @internal Extracts a ScaleInfo Composite into TypeDef.{BTree*, Range*, Wrapper*} */
   #extractComposite (lookupIndex: number, { params, path }: SiType, { fields }: SiTypeDefComposite): TypeDef {
     if (path.length) {
       const pathFirst = path[0].toString();
@@ -775,6 +791,7 @@ export class PortableRegistry extends Struct implements ILookup {
       : this.#extractFields(lookupIndex, fields);
   }
 
+  /** @internal Extracts a ScaleInfo CompositeSet into TypeDef.Set */
   #extractCompositeSet (_: number, params: SiTypeParameter[], fields: SiField[]): TypeDef {
     if (params.length !== 1 || fields.length !== 1) {
       throw new Error('Set handling expects param/field as single entries');
@@ -793,6 +810,7 @@ export class PortableRegistry extends Struct implements ILookup {
     });
   }
 
+  /** @internal Extracts ScaleInfo enum/struct fields into TypeDef.{Struct, Tuple} */
   #extractFields (lookupIndex: number, fields: SiField[]): TypeDef {
     let isStruct = true;
     let isTuple = true;
@@ -853,6 +871,7 @@ export class PortableRegistry extends Struct implements ILookup {
     ));
   }
 
+  /** @internal Apply field aliassed (with no JS conflicts) */
   #extractFieldsAlias (fields: SiField[]): [TypeDef[], Map<string, string>] {
     const alias = new Map<string, string>();
     const sub = new Array<TypeDef>(fields.length);
@@ -886,6 +905,7 @@ export class PortableRegistry extends Struct implements ILookup {
     return [sub, alias];
   }
 
+  /** @internal Extracts an internal Historic (pre V14) type  */
   #extractHistoric (_: number, type: Type): TypeDef {
     return objectSpread({
       displayName: type.toString(),
@@ -893,6 +913,7 @@ export class PortableRegistry extends Struct implements ILookup {
     }, getTypeDef(type));
   }
 
+  /** @internal Extracts a ScaleInfo Primitive into TypeDef.Plain */
   #extractPrimitive (_: number, type: SiType): TypeDef {
     const typeStr = type.def.asPrimitive.type.toString();
 
@@ -902,6 +923,7 @@ export class PortableRegistry extends Struct implements ILookup {
     };
   }
 
+  /** @internal Applies an alias path onto the TypeDef */
   #extractAliasPath (_: number, type: string): TypeDef {
     return {
       info: TypeDefInfo.Plain,
@@ -909,6 +931,7 @@ export class PortableRegistry extends Struct implements ILookup {
     };
   }
 
+  /** @internal Extracts a ScaleInfo Sequence into TypeDef.Vec (with Bytes shortcut) */
   #extractSequence (lookupIndex: number, { type }: SiTypeDefSequence): TypeDef {
     const sub = this.#createSiDef(type);
 
@@ -927,6 +950,7 @@ export class PortableRegistry extends Struct implements ILookup {
     });
   }
 
+  /** @internal Extracts a ScaleInfo Tuple into TypeDef.Tuple */
   #extractTuple (lookupIndex: number, ids: SiTypeDefTuple): TypeDef {
     if (ids.length === 0) {
       return {
@@ -947,6 +971,7 @@ export class PortableRegistry extends Struct implements ILookup {
     });
   }
 
+  /** @internal Extracts a ScaleInfo Variant into TypeDef.{Option, Result, Enum} */
   #extractVariant (lookupIndex: number, { params, path }: SiType, { variants }: SiTypeDefVariant): TypeDef {
     if (path.length) {
       const specialVariant = path[0].toString();
@@ -994,6 +1019,7 @@ export class PortableRegistry extends Struct implements ILookup {
     return this.#extractVariantEnum(lookupIndex, variants);
   }
 
+  /** @internal Extracts a ScaleInfo Variant into TypeDef.Enum */
   #extractVariantEnum (lookupIndex: number, variants: SiVariant[]): TypeDef {
     const sub: (TypeDef & { name: string })[] = [];