Fix various jsdoc rendering and cross-reference issues. (#649)

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

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

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<number|bigint|string|ScInt>} values
+ *    - a list of integer-like values interpreted in big-endian order
+ */
 export class XdrLargeInt {
   /**
    * @type {xdr.LargeInt}

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<scvBool> ]
  * // ]
- * ```
+ *
+ * @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.<type>.value form here because it's faster