Upgrade @truffle/codec's typedoc to v0.20.36

packages/codec/docs/tsconfig.json

@@ -32,7 +32,8 @@
 
   },
   "include": [
-    "./lib/**/*.ts",
-    "./typings/**/*.d.ts"
+    "../../decoder/lib/**/*.ts",
+    "../lib/**/*.ts",
+    "../typings/**/*.d.ts"
   ]
 }

packages/codec/docs/typedoc.json

@@ -1,12 +1,8 @@
 {
   "name": "Truffle Decoding and Encoding",
-  "mode": "modules",
-  "module": "commonjs",
-  "theme": "../../../node_modules/@trufflesuite/typedoc-default-themes/bin/default/",
-  "includeDeclarations": false,
-  "ignoreCompilerErrors": true,
-  "preserveConstEnums": true,
+  "theme": "../../node_modules/@trufflesuite/typedoc-default-themes/bin/default/",
   "excludeExternals": true,
+  "plugin": ["typedoc-plugin-remove-references"],
   "categoryOrder": [
     "Data",
     "ABI data location",
@@ -29,6 +25,5 @@
   ],
   "exclude": [
     "**/test/*"
-  ],
-  "target": "ES6"
+  ]
 }

packages/codec/lib/abi-data/decode/index.ts

@@ -1,3 +1,9 @@
+/**
+ * @protected
+ *
+ * @packageDocumentation
+ */
+
 import debugModule from "debug";
 const debug = debugModule("codec:abi-data:decode");
 

packages/codec/lib/abi-data/import/index.ts

@@ -1,3 +1,9 @@
+/**
+ * @protected
+ *
+ * @packageDocumentation
+ */
+
 import debugModule from "debug";
 const debug = debugModule("codec:abi-data:import");
 

packages/codec/lib/abi-data/index.ts

@@ -1,24 +1,23 @@
+/**
+ * For allocation, encoding, and decoding of locations related to the ABI
+ * (calldata in Solidity, events, etc.)
+ *
+ * @category ABI data location
+ *
+ * @packageDocumentation
+ */
+
 import * as Allocate from "./allocate";
 export { Allocate };
 
 import * as Encode from "./encode";
 export { Encode };
 
 import * as Decode from "./decode";
-export {
-  /**
-   * @protected
-   */
-  Decode
-};
+export { Decode };
 
 import * as Import from "./import";
-export {
-  /**
-   * @protected
-   */
-  Import
-};
+export { Import };
 
 export * from "./types";
 

packages/codec/lib/ast-constant/decode/index.ts

@@ -1,3 +1,8 @@
+/**
+ * @protected
+ *
+ * @packageDocumentation
+ */
 import debugModule from "debug";
 const debug = debugModule("codec:ast:decode");
 

packages/codec/lib/ast-constant/index.ts

@@ -1,15 +1,13 @@
+/**
+ * For reading/decoding constants expressed as AST nodes
+ *
+ * @category Solidity data location
+ *
+ * @packageDocumentation
+ */
+
 import * as Read from "./read";
-export {
-  /**
-   * @protected
-   */
-  Read
-};
+export { Read };
 
 import * as Decode from "./decode";
-export {
-  /**
-   * @protected
-   */
-  Decode
-};
+export { Decode };

packages/codec/lib/ast-constant/read/index.ts

@@ -1,3 +1,9 @@
+/**
+ * @protected
+ *
+ * @packageDocumentation
+ */
+
 import debugModule from "debug";
 const debug = debugModule("codec:ast:read");
 

packages/codec/lib/ast/import/index.ts

@@ -1,3 +1,9 @@
+/**
+ * @protected
+ *
+ * @packageDocumentation
+ */
+
 import debugModule from "debug";
 const debug = debugModule("codec:ast:import");
 

packages/codec/lib/ast/index.ts

@@ -4,9 +4,4 @@ import * as Utils from "./utils";
 export { Utils };
 
 import * as Import from "./import";
-export {
-  /**
-   * @protected
-   */
-  Import
-};
+export { Import };

packages/codec/lib/basic/index.ts

@@ -1,3 +1,14 @@
+/**
+ * For decoding of primitives and constants
+ *
+ * @protected
+ *
+ * @packageDocumentation
+ */
+//Category: Common data location
+//[NOT making this an actual category for now
+//since there's nothing public in it]
+
 import * as Decode from "./decode";
 export {
   /**

packages/codec/lib/bytes/index.ts

@@ -1,3 +1,13 @@
+/**
+ * Contains functions for dealing with raw bytestrings
+ * @protected
+ *
+ * @packageDocumentation
+ */
+//Category: Common data location
+//[NOT making this an actual category for now
+//since there's nothing public in it]
+
 import * as Read from "./read";
 export {
   /**

packages/codec/lib/format/errors.ts

@@ -1,3 +1,9 @@
+/**
+ * Contains the types for error and `ErrorResult` objects.
+ * @category Main Format
+ *
+ * @packageDocumentation
+ */
 import debugModule from "debug";
 const debug = debugModule("codec:format:errors");
 

packages/codec/lib/format/index.ts

@@ -1,23 +1,180 @@
+/**
+ * # Codec Output Format
+ *
+ * ## Module information
+ *
+ * This module primarily defines TypeScript types for the output format
+ * used in results provided by packages
+ * `@truffle/decoder@^4.0.0` and `@truffle/codec@^0.1.0`.
+ *
+ * See below for complete listing or continue reading
+ * [Format information](#format-information) to learn about this format.
+ *
+ * ### How to import
+ *
+ * Import either as part of Codec or by itself:
+ *
+ * ```typescript
+ * // when importing entire Codec, use Codec.Format.*:
+ * import * as Codec from "@truffle/codec";
+ *
+ * // or import Format directly:
+ * import { Format } from "@truffle/codec";
+ * ```
+ *
+ * ![Example struct decoding](media://example-struct-decoding.png)
+ *
+ * ## Format information
+ *
+ * This format is intended for use in smart contract and dapp development
+ * tools and libraries, and for use in display contexts, such as when
+ * building on-screen components to show transaction and smart contract
+ * state information.
+ *
+ * This format seeks to provide an exhaustive schema for JavaScript
+ * objects to encode **lossless**, **machine-readable** representations of
+ * all possible Solidity and ABI data types and all possible values of those
+ * types.
+ *
+ * This format targets types and values understood by the
+ * [Solidity programming language](https://solidity.readthedocs.io) and
+ * the [Contract ABI specification](https://solidity.readthedocs.io/en/v0.5.3/abi-spec.html),
+ * within the context of the [Ethereum Virtual Machine](https://ethereum.github.io/yellowpaper/paper.pdf)
+ * (EVM) and in raw data for transactions and logs according to the
+ * [Ethereum JSON RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC).
+ *
+ * Objects in this format may be deeply nested and/or contain circular
+ * dependencies. As such, **do not** serialize objects in this format or
+ * otherwise attempt to display them in full without considering potential
+ * risk. **Objects in this format are for the machine to read, not humans!**
+ * This module provides utilities for inspecting objects in this format,
+ * including the **safe** [[Format.Utils.Inspect.ResultInspector]] wrapper
+ * (for [util.inspect](https://nodejs.org/api/util.html#util_util_inspect_object_options)),
+ * and the **unsafe** [[Format.Utils.Inspect.nativize]] function. For more
+ * information, please see the documentation for those utilities.
+ *
+ * ### Specification
+ *
+ * Individual decoded values are represented by objects of the type
+ * [[Format.Values.Result]], which contain the following fields:
+ *   1. `type`: This is a [[Format.Types.Type|`Type`]] object describing the value's
+ *     type.  Each `Type` has a `typeClass` field describing the overall broad type,
+ *     such as `"uint"` or `"bytes"`, together with additional information that gives
+ *     the specific type.  For full detail, see [[Format.Types]].
+ *
+ *   2. `kind`: This is either `"value"`, in which case the `Result` is a
+ *     [[Format.Values.Value|`Value`]], or `"error"`, in which case the `Result` is an
+ *     [[Format.Errors.ErrorResult|`ErrorResult`]].  In the former case, there will be
+ *     a `value` field containin the decoded value.  In the latter case, there will be
+ *     an `error` field indicating what went wrong.  *Warning*: When decoding a
+ *     complex type, such as an array, mapping, or array, getting a kind of `"value"`
+ *     does not necessarily mean the individual elements were decoded successfully.
+ *     Even if the `Result` for the array (mapping, struct) as a whole has kind
+ *     `"value"`, the elements might still have kind `"error"`.
+ *
+ *   3. `value`: As mentioned, this is included when `kind` is equal to `"value"`.
+ *     It contains information about the actual decoded value.  See
+ *     [[Format.Values|`Format.Values`]] for more information.
+ *
+ *   4. `error`: The alternative to `value`.  Generally includes information about
+ *     the raw data that led to the error.  See [[Format.Errors|`Format.Errors`]] for
+ *     more information.
+ *
+ *   5. `reference`: This field is a debugger-only feature and does not
+ *      apply to results returned by  @truffle/decoder, so it won't be documented here.
+ *
+ * ### Values vs. errors
+ *
+ * It's worth taking a moment here to answer the question: What counts as a value,
+ * and what counts as an error?
+ *
+ * In general, the answer is that anything that can be generated via Solidity
+ * alone (i.e. no assembly), with correctly-encoded inputs, and without making use
+ * of compiler bugs, is a value, not an error.  That means that, for instance, the
+ * following things are values, not errors:
+ *   - A variable of contract type whose address does not actually hold a
+ *     contract of that type;
+ *   - An external function pointer that does not correspond to a valid
+ *     function;
+ *   - A string containing invalid UTF-8;
+ *   - ..., etc.
+ *
+ * By contrast, the following *are* errors:
+ *   - A `bool` which is neither `false` (0) nor `true` (1);
+ *   - An `enum` which is out of range;
+ *   - ..., etc.
+ *
+ * (You may be wondering about the enum case here, because if you go sufficiently
+ * far back, to Solidity 0.4.4 or earlier, it *was* possible to generate
+ * out-of-range enums without resorting to assembly or compiler bugs.  However,
+ * enums are only supported in full mode (see
+ * [Notes on decoding modes](../#decoding-modes)),
+ * which only supports 0.4.12 and later, so
+ * we consider out-of-range enums an error.  There are also additional technical
+ * reasons why supporting out-of-range enums as a value would be difficult.)
+ *
+ * There are three special cases here that are likely worthy of note.
+ *
+ * Firstly, internal function pointers currently can't be meaningfully
+ * decoded via @truffle/decoder.  However, they decode to a bare-bones value,
+ * not an error, as it is (in a sense) our own fault that we can't decode
+ * these, so it doesn't make sense to report an error, which would mean that
+ * something is wrong with the encoded data itself.  This value that it
+ * decodes to will give the program counter values it corresponds to, but
+ * will not include the function name or defining class, as @truffle/decoder
+ * is not presently capable of that.  For now, full decoding of internal
+ * function pointers remains a debugger-only feature.  (But limited support for
+ * this via @truffle/decoder is planned for the future.)
+ *
+ * (When using the debugger, an invalid internal function pointer will decode to an
+ * error.  However, when using @truffle/decoder, we have no way of discerning whether
+ * the pointer is valid or not, so internal function pointers will always decode to
+ * a value, if an uninformative one.)
+ *
+ * Secondly, when decoding events, it is impossible to decode indexed parameters
+ * of reference type.  Thus, these decode to an error
+ * (`IndexedReferenceTypeError`, which see) rather than to a value.
+ *
+ * Thirdly, the decoder is currently limited when it comes to decoding state
+ * variables that are declared constant, and not all such variables are yet
+ * supported in decoding; attempting to decode one of these that is not currently
+ * supported will yield an error.
+ *
+ * Similarly, there are various things that decode to errors for technical reasons.
+ * Objects with encoded length fields larger than what fits in a JavaScript safe
+ * integer, or pointed to by pointers with values larger than what fits in a
+ * JavaScript safe integer, will decode to errors, even if they may technically be
+ * legal.  Such cases are impractical to handle and should never come up in real
+ * use so we decode them to errors.  Errors may also be returned in case of an
+ * error in attempting to read the data to be decoded.
+ *
+ * Finally, except when decoding events, we do not return an error if the pointers
+ * in an ABI-encoded array or tuple are arranged in a nonstandard way, or if
+ * strings or bytestrings are incorrectly padded, because it is not worth the
+ * trouble to detect these conditions.
+ *
+ *
+ * ## Notes on this documentation
+ *
+ * Most of this doesn't have explanatory documentation
+ * because it's largely self-explanatory, but particularly
+ * non-obvious parts have been documented for clarity.
+ *
+ * A note on optional fields: A number of types or values
+ * have optional fields.  These contain helpful
+ * but non-essential information, or information which
+ * for technical reasons we can't guarantee we can determine.
+ *
+ * @category Data
+ *
+ * @packageDocumentation
+ */
 import { Types, Values, Errors } from "./common";
 import * as Utils from "./utils";
 
 export {
-  /**
-   * Contains the types for type objects, and some
-   * functions for working with them.
-   *
-   * @category Main Format
-   */
   Types,
-  /**
-   * Contains the types for value and result objects.
-   * @category Main Format
-   */
   Values,
-  /**
-   * Contains the types for error and `ErrorResult` objects.
-   * @category Main Format
-   */
   Errors,
   Utils
 };