From 6696cae8adf6d2ce7f2410eaf47e5ec53b6736d3 Mon Sep 17 00:00:00 2001 From: George Date: Tue, 18 Jul 2023 10:51:48 -0700 Subject: [PATCH] Fix various jsdoc rendering and cross-reference issues. (#649) --- src/numbers/index.js | 2 - src/numbers/sc_int.js | 6 +-- src/numbers/xdr_large_int.js | 13 ++++++ src/scval.js | 78 +++++++++++++++++------------------- 4 files changed, 52 insertions(+), 47 deletions(-) diff --git a/src/numbers/index.js b/src/numbers/index.js index 08f45a69..4fde1dea 100644 --- a/src/numbers/index.js +++ b/src/numbers/index.js @@ -14,13 +14,11 @@ export { XdrLargeInt }; * you can pass it to the constructor of {@link XdrLargeInt}. * * @example - * ```js * let scv = contract.call("add", x, y); // assume it returns an xdr.ScVal * let bigi = scValToBigInt(scv); * * new ScInt(bigi); // if you don't care about types, and * new XdrLargeInt('i128', bigi); // if you do - * ``` * * @param {xdr.ScVal} scv - the raw XDR value to parse into an integer * @returns {bigint} the native value of this input value diff --git a/src/numbers/sc_int.js b/src/numbers/sc_int.js index b54c57ca..45210c5b 100644 --- a/src/numbers/sc_int.js +++ b/src/numbers/sc_int.js @@ -8,11 +8,10 @@ import { XdrLargeInt } from './xdr_large_int'; * * If you need to create a native BigInt from a list of integer "parts" (for * example, you have a series of encoded 32-bit integers that represent a larger - * value), you can use the lower level abstraction {@link XdrLargeInt}. For example, - * you could do `new XdrLargeInt('u128', bytes...).toBigInt()`. + * value), you can use the lower level abstraction {@link XdrLargeInt}. For + * example, you could do `new XdrLargeInt('u128', bytes...).toBigInt()`. * * @example - * ```js * import sdk from "stellar-base"; * * // You have an ScVal from a contract and want to parse it into JS native. @@ -53,7 +52,6 @@ import { XdrLargeInt } from './xdr_large_int'; * * // Or reinterpret it as a different type (size permitting): * const scv = i.toI64(); - * ``` * * @param {number|bigint|string|ScInt} value - a single, integer-like value * which will be interpreted in the smallest appropriate XDR type supported diff --git a/src/numbers/xdr_large_int.js b/src/numbers/xdr_large_int.js index 31c51a6e..899d97ee 100644 --- a/src/numbers/xdr_large_int.js +++ b/src/numbers/xdr_large_int.js @@ -8,6 +8,19 @@ import { Int256 } from './int256'; import xdr from '../xdr'; +/** + * A wrapper class to represent large XDR-encodable integers. + * + * This operates at a lower level than {@link ScInt} by forcing you to specify + * the type / width / size in bits of the integer you're targeting, regardless + * of the input value(s) you provide. + * + * @param {string} type - force a specific data type. the type choices + * are: 'i64', 'u64', 'i128', 'u128', 'i256', and 'u256' (default: the + * smallest one that fits the `value`) + * @param {number|bigint|string|ScInt|Array} values + * - a list of integer-like values interpreted in big-endian order + */ export class XdrLargeInt { /** * @type {xdr.LargeInt} diff --git a/src/scval.js b/src/scval.js index 57d68e1a..77ca9c03 100644 --- a/src/scval.js +++ b/src/scval.js @@ -1,41 +1,3 @@ -/** - * Provides conversions from smart contract XDR values ({@link xdr.ScVal}) to - * native JavaScript types. - * - * @example - * ```js - * import { nativeToScVal, scValToNative, ScInt, xdr } from 'stellar-base'; - * - * let gigaMap = { - * bool: true, - * void: null, - * u32: xdr.ScVal.scvU32(1), - * i32: xdr.ScVal.scvI32(1), - * u64: 1n, - * i64: -1n, - * u128: new ScInt(1).toU128(), - * i128: new ScInt(1).toI128(), - * u256: new ScInt(1).toU256(), - * i256: new ScInt(1).toI256(), - * map: { - * arbitrary: 1n, - * nested: 'values', - * etc: false - * }, - * vec: ['same', 'type', 'list'], - * }; - * - * // then, simply: - * let scv = nativeToScVal(gigaMap); // scv.switch() == xdr.ScValType.scvMap() - * - * // then... - * someContract.call("method", scv); - * - * // Similarly, the inverse should work: - * scValToNative(scv) == gigaMap; // true - * ``` - */ - import xdr from './xdr'; import { Address } from './address'; @@ -46,6 +8,9 @@ import { ScInt, scValToBigInt } from './numbers/index'; * Attempts to convert native types into smart contract values * ({@link xdr.ScVal}). * + * Provides conversions from smart contract XDR values ({@link xdr.ScVal}) to + * native JavaScript types. + * * The conversions are as follows: * * - xdr.ScVal -> passthrough @@ -112,8 +77,6 @@ import { ScInt, scValToBigInt } from './numbers/index'; * though this does not apply for types that ignore `opts` (e.g. addresses). * * @example - * - * ```js * nativeToScVal(1000); // gives ScValType === scvU64 * nativeToScVal(1000n); // gives ScValType === scvU64 * nativeToScVal(1n << 100n); // gives ScValType === scvU128 @@ -136,7 +99,39 @@ import { ScInt, scValToBigInt } from './numbers/index'; * // [ scvSymbol, scvI128 ], * // [ scvString, scvArray ] * // ] - * ``` + * + * @example + * import { nativeToScVal, scValToNative, ScInt, xdr } from 'stellar-base'; + * + * let gigaMap = { + * bool: true, + * void: null, + * u32: xdr.ScVal.scvU32(1), + * i32: xdr.ScVal.scvI32(1), + * u64: 1n, + * i64: -1n, + * u128: new ScInt(1).toU128(), + * i128: new ScInt(1).toI128(), + * u256: new ScInt(1).toU256(), + * i256: new ScInt(1).toI256(), + * map: { + * arbitrary: 1n, + * nested: 'values', + * etc: false + * }, + * vec: ['same', 'type', 'list'], + * }; + * + * // then, simply: + * let scv = nativeToScVal(gigaMap); // scv.switch() == xdr.ScValType.scvMap() + * + * // then... + * someContract.call("method", scv); + * + * // Similarly, the inverse should work: + * scValToNative(scv) == gigaMap; // true + * + * @see scValToNative */ export function nativeToScVal(val, opts = {}) { switch (typeof val) { @@ -272,6 +267,7 @@ export function nativeToScVal(val, opts = {}) { * @param {xdr.ScVal} scv - the input smart contract value * * @returns {any} + * @see nativeToScVal */ export function scValToNative(scv) { // we use the verbose xdr.ScValType..value form here because it's faster