diff --git a/packages/codec/docs/tsconfig.json b/packages/codec/docs/tsconfig.json index 4b38a637bf9..0b6b28f739a 100644 --- a/packages/codec/docs/tsconfig.json +++ b/packages/codec/docs/tsconfig.json @@ -32,7 +32,8 @@ }, "include": [ - "./lib/**/*.ts", - "./typings/**/*.d.ts" + "../../decoder/lib/**/*.ts", + "../lib/**/*.ts", + "../typings/**/*.d.ts" ] } diff --git a/packages/codec/docs/typedoc.json b/packages/codec/docs/typedoc.json index 8ebd91a2860..b4073b3ed0c 100644 --- a/packages/codec/docs/typedoc.json +++ b/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" + ] } diff --git a/packages/codec/lib/abi-data/decode/index.ts b/packages/codec/lib/abi-data/decode/index.ts index fff623fcd45..b53c4475e0f 100644 --- a/packages/codec/lib/abi-data/decode/index.ts +++ b/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"); diff --git a/packages/codec/lib/abi-data/import/index.ts b/packages/codec/lib/abi-data/import/index.ts index 0ba7ddf375e..03b41eb930f 100644 --- a/packages/codec/lib/abi-data/import/index.ts +++ b/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"); diff --git a/packages/codec/lib/abi-data/index.ts b/packages/codec/lib/abi-data/index.ts index 913a5575cc7..6d5a7e6191a 100644 --- a/packages/codec/lib/abi-data/index.ts +++ b/packages/codec/lib/abi-data/index.ts @@ -1,3 +1,12 @@ +/** + * 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 }; @@ -5,20 +14,10 @@ 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"; diff --git a/packages/codec/lib/ast-constant/decode/index.ts b/packages/codec/lib/ast-constant/decode/index.ts index b2714e8e065..6a8f77432ae 100644 --- a/packages/codec/lib/ast-constant/decode/index.ts +++ b/packages/codec/lib/ast-constant/decode/index.ts @@ -1,3 +1,8 @@ +/** + * @protected + * + * @packageDocumentation + */ import debugModule from "debug"; const debug = debugModule("codec:ast:decode"); diff --git a/packages/codec/lib/ast-constant/index.ts b/packages/codec/lib/ast-constant/index.ts index 38a2ed2dabf..36d59caac33 100644 --- a/packages/codec/lib/ast-constant/index.ts +++ b/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 }; diff --git a/packages/codec/lib/ast-constant/read/index.ts b/packages/codec/lib/ast-constant/read/index.ts index d803f03aefe..7e3e62cd4e9 100644 --- a/packages/codec/lib/ast-constant/read/index.ts +++ b/packages/codec/lib/ast-constant/read/index.ts @@ -1,3 +1,9 @@ +/** + * @protected + * + * @packageDocumentation + */ + import debugModule from "debug"; const debug = debugModule("codec:ast:read"); diff --git a/packages/codec/lib/ast/import/index.ts b/packages/codec/lib/ast/import/index.ts index fe83550b0d4..64b1998f615 100644 --- a/packages/codec/lib/ast/import/index.ts +++ b/packages/codec/lib/ast/import/index.ts @@ -1,3 +1,9 @@ +/** + * @protected + * + * @packageDocumentation + */ + import debugModule from "debug"; const debug = debugModule("codec:ast:import"); diff --git a/packages/codec/lib/ast/index.ts b/packages/codec/lib/ast/index.ts index 419f4b129c4..603ed6cd372 100644 --- a/packages/codec/lib/ast/index.ts +++ b/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 }; diff --git a/packages/codec/lib/basic/index.ts b/packages/codec/lib/basic/index.ts index fba47f10c64..f7726986df9 100644 --- a/packages/codec/lib/basic/index.ts +++ b/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 { /** diff --git a/packages/codec/lib/bytes/index.ts b/packages/codec/lib/bytes/index.ts index dcbe1e67b88..5d57181b66e 100644 --- a/packages/codec/lib/bytes/index.ts +++ b/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 { /** diff --git a/packages/codec/lib/format/errors.ts b/packages/codec/lib/format/errors.ts index f9912bc8cae..22f18953272 100644 --- a/packages/codec/lib/format/errors.ts +++ b/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"); diff --git a/packages/codec/lib/format/index.ts b/packages/codec/lib/format/index.ts index 3f5495629e5..07512f2a508 100644 --- a/packages/codec/lib/format/index.ts +++ b/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 }; diff --git a/packages/codec/lib/format/types.ts b/packages/codec/lib/format/types.ts index d0cb0272b81..0713b21eb7e 100644 --- a/packages/codec/lib/format/types.ts +++ b/packages/codec/lib/format/types.ts @@ -1,3 +1,12 @@ +/** + * Contains the types for type objects, and some + * functions for working with them. + * + * @category Main Format + * + * @packageDocumentation + */ + import debugModule from "debug"; const debug = debugModule("codec:format:types"); diff --git a/packages/codec/lib/format/utils/exception.ts b/packages/codec/lib/format/utils/exception.ts index 51421bd9837..e2453e4459d 100644 --- a/packages/codec/lib/format/utils/exception.ts +++ b/packages/codec/lib/format/utils/exception.ts @@ -1,3 +1,8 @@ +/** + * @protected + * + * @packageDocumentation + */ import debugModule from "debug"; const debug = debugModule("codec:format:utils:exception"); diff --git a/packages/codec/lib/format/utils/index.ts b/packages/codec/lib/format/utils/index.ts index 4da6e58040a..f94a422190e 100644 --- a/packages/codec/lib/format/utils/index.ts +++ b/packages/codec/lib/format/utils/index.ts @@ -1,10 +1,5 @@ import * as Exception from "./exception"; -export { - /** - * @protected - */ - Exception -}; +export { Exception }; import * as Inspect from "./inspect"; export { Inspect }; diff --git a/packages/codec/lib/format/values.ts b/packages/codec/lib/format/values.ts index 9809cdaa410..15ef7fa3eaa 100644 --- a/packages/codec/lib/format/values.ts +++ b/packages/codec/lib/format/values.ts @@ -1,3 +1,10 @@ +/** + * Contains the types for value and result objects. + * @category Main Format + * + * @packageDocumentation + */ + import debugModule from "debug"; const debug = debugModule("codec:format:values"); diff --git a/packages/codec/lib/index.ts b/packages/codec/lib/index.ts index fbf7856622a..a9a813c491a 100644 --- a/packages/codec/lib/index.ts +++ b/packages/codec/lib/index.ts @@ -58,184 +58,14 @@ * read or copy). * * @module @truffle/codec - */ /** */ + * @packageDocumentation + */ //So, what shall codec export...? //First: export the data format import * as Format from "@truffle/codec/format"; -export { - /** -# 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 - */ - Format -}; +export { Format }; //now... various low-level stuff we want to export! //the actual decoding functions and related errors @@ -287,45 +117,12 @@ export { // data locations - common import * as Basic from "./basic"; import * as Bytes from "./bytes"; -export { - /** - * For decoding of primitives and constants - * - * @protected - */ - Basic, - //Category: Common data location - //[NOT making this an actual category for now - //since there's nothing public in it] - /** - * Contains functions for dealing with raw bytestrings - * @protected - */ - Bytes - //Category: Common data location - //[NOT making this an actual category for now - //since there's nothing public in it] -}; +export { Basic, Bytes }; // data locations - abi import * as AbiData from "./abi-data"; import * as Topic from "./topic"; -export { - /** - * For allocation, encoding, and decoding of locations related to the ABI - * (calldata in Solidity, events, etc.) - * - * @category ABI data location - */ - AbiData, - /** - * For decoding of event topics - * - * @protected - * @category ABI data location - */ - Topic -}; +export { AbiData, Topic }; // data locations - solidity import * as MappingKey from "./mapping-key"; @@ -336,43 +133,11 @@ import * as Storage from "./storage"; import * as AstConstant from "./ast-constant"; export { - /** - * For encoding mapping keys - * - * @protected - * @category Solidity data location - */ MappingKey, - /** - * For allocation and decoding of memory data - * - * @category Solidity data location - */ Memory, - /** - * For decoding of special/magic variables - * - * @protected - * @category Solidity data location - */ Special, - /** - * For decoding stack variables - * - * @category Solidity data location - */ Stack, - /** - * For allocation and decoding of storage variables - * - * @category Solidity data location - */ Storage, - /** - * For reading/decoding constants expressed as AST nodes - * - * @category Solidity data location - */ AstConstant }; diff --git a/packages/codec/lib/mapping-key/index.ts b/packages/codec/lib/mapping-key/index.ts index 775f89634cf..418acabfad3 100644 --- a/packages/codec/lib/mapping-key/index.ts +++ b/packages/codec/lib/mapping-key/index.ts @@ -1,3 +1,12 @@ +/** + * For encoding mapping keys + * + * @protected + * @category Solidity data location + * + * @packageDocumentation + */ + import * as Encode from "./encode"; export { /** diff --git a/packages/codec/lib/memory/decode/index.ts b/packages/codec/lib/memory/decode/index.ts index 825a7ed5d14..0769899a0e9 100644 --- a/packages/codec/lib/memory/decode/index.ts +++ b/packages/codec/lib/memory/decode/index.ts @@ -1,3 +1,9 @@ +/** + * @protected + * + * @packageDocumentation + */ + import debugModule from "debug"; const debug = debugModule("codec:memory:decode"); diff --git a/packages/codec/lib/memory/index.ts b/packages/codec/lib/memory/index.ts index 43544f84a25..2c338ccdec3 100644 --- a/packages/codec/lib/memory/index.ts +++ b/packages/codec/lib/memory/index.ts @@ -1,10 +1,13 @@ +/** + * For allocation and decoding of memory data + * + * @category Solidity data location + * + * @packageDocumentation + */ + import * as Allocate from "./allocate"; export { Allocate }; import * as Decode from "./decode"; -export { - /** - * @protected - */ - Decode -}; +export { Decode }; diff --git a/packages/codec/lib/special/index.ts b/packages/codec/lib/special/index.ts index ba99155b562..1fe80385918 100644 --- a/packages/codec/lib/special/index.ts +++ b/packages/codec/lib/special/index.ts @@ -1,3 +1,12 @@ +/** + * For decoding of special/magic variables + * + * @protected + * @category Solidity data location + * + * @packageDocumentation + */ + import * as Decode from "./decode"; export { /** diff --git a/packages/codec/lib/stack/decode/index.ts b/packages/codec/lib/stack/decode/index.ts index 5fc2dd6db39..c0b67b1afbc 100644 --- a/packages/codec/lib/stack/decode/index.ts +++ b/packages/codec/lib/stack/decode/index.ts @@ -1,3 +1,9 @@ +/** + * @protected + * + * @packageDocumentation + */ + import debugModule from "debug"; const debug = debugModule("codec:stack:decode"); diff --git a/packages/codec/lib/stack/index.ts b/packages/codec/lib/stack/index.ts index b7679256b05..1f6a49dc357 100644 --- a/packages/codec/lib/stack/index.ts +++ b/packages/codec/lib/stack/index.ts @@ -1,10 +1,13 @@ +/** + * For decoding stack variables + * + * @category Solidity data location + * + * @packageDocumentation + */ + import * as Decode from "./decode"; -export { - /** - * @protected - */ - Decode -}; +export { Decode }; import * as Read from "./read"; export { Read }; diff --git a/packages/codec/lib/storage/decode/index.ts b/packages/codec/lib/storage/decode/index.ts index 56cf094f8f9..7b05ba33dcf 100644 --- a/packages/codec/lib/storage/decode/index.ts +++ b/packages/codec/lib/storage/decode/index.ts @@ -1,3 +1,9 @@ +/** + * @protected + * + * @packageDocumentation + */ + import debugModule from "debug"; const debug = debugModule("codec:storage:decode"); diff --git a/packages/codec/lib/storage/index.ts b/packages/codec/lib/storage/index.ts index 36b1dfc5325..0b3dbb20379 100644 --- a/packages/codec/lib/storage/index.ts +++ b/packages/codec/lib/storage/index.ts @@ -1,3 +1,11 @@ +/** + * For allocation and decoding of storage variables + * + * @category Solidity data location + * + * @packageDocumentation + */ + export * from "./types"; import * as Utils from "./utils"; @@ -7,17 +15,7 @@ import * as Allocate from "./allocate"; export { Allocate }; import * as Decode from "./decode"; -export { - /** - * @protected - */ - Decode -}; +export { Decode }; import * as Read from "./read"; -export { - /** - * @protected - */ - Read -}; +export { Read }; diff --git a/packages/codec/lib/storage/read/index.ts b/packages/codec/lib/storage/read/index.ts index 35aea649228..47c2f5453d3 100644 --- a/packages/codec/lib/storage/read/index.ts +++ b/packages/codec/lib/storage/read/index.ts @@ -1,3 +1,9 @@ +/** + * @protected + * + * @packageDocumentation + */ + import debugModule from "debug"; const debug = debugModule("codec:storage:read"); diff --git a/packages/codec/lib/topic/index.ts b/packages/codec/lib/topic/index.ts index 4c561984198..88f24730eae 100644 --- a/packages/codec/lib/topic/index.ts +++ b/packages/codec/lib/topic/index.ts @@ -1,3 +1,11 @@ +/** + * For decoding of event topics + * + * @protected + * @category ABI data location + * + * @packageDocumentation + */ import * as Decode from "./decode"; export { /** diff --git a/packages/codec/package.json b/packages/codec/package.json index 3e719147949..2c9d57287b1 100644 --- a/packages/codec/package.json +++ b/packages/codec/package.json @@ -38,7 +38,6 @@ "web3-utils": "1.3.6" }, "devDependencies": { - "@gnd/typedoc": "0.15.0-0", "@truffle/abi-utils": "^0.2.1", "@truffle/compile-common": "^0.7.7", "@truffle/contract-schema": "^3.4.1", @@ -55,8 +54,8 @@ "@types/utf8": "^2.1.6", "@zerollup/ts-transform-paths": "^1.7.3", "ttypescript": "^1.5.7", - "typedoc": "0.15.0", - "typedoc-plugin-external-module-name": "^2.1.0", + "typedoc": "^0.20.36", + "typedoc-plugin-remove-references": "^0.0.5", "typescript": "^4.1.4" }, "keywords": [ diff --git a/packages/codec/scripts/generate-docs b/packages/codec/scripts/generate-docs index 620bc877add..b8340957d15 100755 --- a/packages/codec/scripts/generate-docs +++ b/packages/codec/scripts/generate-docs @@ -1,7 +1,7 @@ #!/bin/bash # bin -typedoc=../../node_modules/@gnd/typedoc/bin/typedoc +typedoc=../../node_modules/typedoc/bin/typedoc DIST_HTML=./dist/docs DIST_JSON=./dist/api.json @@ -22,4 +22,4 @@ $typedoc \ --out $DIST_HTML \ --json $DIST_JSON \ --media $MEDIA \ - $CODEC $DECODER # entrypoints to display + $CODEC $DECODER $@ # entrypoints to display diff --git a/packages/decoder/lib/index.ts b/packages/decoder/lib/index.ts index 1e72aeef601..fe8ca699695 100644 --- a/packages/decoder/lib/index.ts +++ b/packages/decoder/lib/index.ts @@ -134,7 +134,8 @@ One can find more advanced decoding examples with documentation for these individual functions. * * @module @truffle/decoder - */ /** */ + * @packageDocumentation + */ import { ContractDecoder, diff --git a/yarn.lock b/yarn.lock index 27c6927b0b7..887155a39b5 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1587,23 +1587,6 @@ leveldown "5.6.0" secp256k1 "4.0.2" -"@gnd/typedoc@0.15.0-0": - version "0.15.0-0" - resolved "https://registry.yarnpkg.com/@gnd/typedoc/-/typedoc-0.15.0-0.tgz#bb2fd8f316e496cabab0f33966f5f1581e974f86" - integrity sha512-wKtap5cyeOvJ3xWDHnZ6XUWzGqQ4RvrhKbT8UDyhQBJ+1bbKRI6e9dlWw/WX5k6wYoDUi4ZY1nLTZLY3a12i6Q== - dependencies: - "@types/minimatch" "3.0.3" - fs-extra "^8.1.0" - handlebars "^4.1.2" - highlight.js "^9.15.8" - lodash "^4.17.15" - marked "^0.7.0" - minimatch "^3.0.0" - progress "^2.0.3" - shelljs "^0.8.3" - typedoc-default-themes "^0.6.0" - typescript "3.6.x" - "@gql2ts/from-schema@^2.0.0-4": version "2.0.0-4" resolved "https://registry.yarnpkg.com/@gql2ts/from-schema/-/from-schema-2.0.0-4.tgz#9927dd0d991e64101ad443cadee8c47f347f1db9" @@ -4332,7 +4315,7 @@ resolved "https://registry.yarnpkg.com/@types/mime/-/mime-2.0.0.tgz#5a7306e367c539b9f6543499de8dd519fac37a8b" integrity sha512-A2TAGbTFdBw9azHbpVd+/FkdW2T6msN1uct1O9bH3vTerEHKZhTXJUQXy+hNq1B0RagfU8U+KBdqiZpxjhOUQA== -"@types/minimatch@*", "@types/minimatch@3.0.3": +"@types/minimatch@*": version "3.0.3" resolved "https://registry.yarnpkg.com/@types/minimatch/-/minimatch-3.0.3.tgz#3dca0e3f33b200fc7d1139c0cd96c1268cadfd9d" integrity sha512-tHq6qdbT9U1IRSGf14CL0pUlULksvY9OZ+5eEgl1N7t+OA3tGvNpxJCzuKQlsNgCVwbAs670L1vcVQi8j9HjnA== @@ -14116,7 +14099,7 @@ hamt-sharding@^1.0.0: dependencies: sparse-array "^1.3.1" -handlebars@^4.1.2, handlebars@^4.4.0, handlebars@^4.5.3: +handlebars@^4.1.2, handlebars@^4.4.0: version "4.5.3" resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.5.3.tgz#5cf75bd8714f7605713511a56be7c349becb0482" integrity sha512-3yPecJoJHK/4c6aZhSvxOyG4vJKDshV36VHp0iVCDVh7o9w2vwi3NSnL2MMPj3YdduqaBcu7cGbggJQM0br9xA== @@ -14387,13 +14370,6 @@ highlight.js@^10.4.1: resolved "https://registry.yarnpkg.com/highlight.js/-/highlight.js-10.4.1.tgz#d48fbcf4a9971c4361b3f95f302747afe19dbad0" integrity sha512-yR5lWvNz7c85OhVAEAeFhVCc/GV4C30Fjzc/rCP0aCWzc1UUOPUk55dK/qdwTZHBvMZo+eZ2jpk62ndX/xMFlg== -highlight.js@^9.15.8: - version "9.17.1" - resolved "https://registry.yarnpkg.com/highlight.js/-/highlight.js-9.17.1.tgz#14a4eded23fd314b05886758bb906e39dd627f9a" - integrity sha512-TA2/doAur5Ol8+iM3Ov7qy3jYcr/QiJ2eDTdRF4dfbjG7AaaB99J5G+zSl11ljbl6cIcahgPY6SKb3sC3EJ0fw== - dependencies: - handlebars "^4.5.3" - highlightjs-solidity@^1.1.1: version "1.1.1" resolved "https://registry.yarnpkg.com/highlightjs-solidity/-/highlightjs-solidity-1.1.1.tgz#ed0f246d0f8cba647291baff68fb131252067424" @@ -19960,11 +19936,6 @@ marked@0.3.19: resolved "https://registry.yarnpkg.com/marked/-/marked-0.3.19.tgz#5d47f709c4c9fc3c216b6d46127280f40b39d790" integrity sha512-ea2eGWOqNxPcXv8dyERdSr/6FmzvWwzjMxpfGB/sbMccXoct+xY+YukPD+QTUZwyvK7BZwcr4m21WBOW41pAkg== -marked@^0.7.0: - version "0.7.0" - resolved "https://registry.yarnpkg.com/marked/-/marked-0.7.0.tgz#b64201f051d271b1edc10a04d1ae9b74bb8e5c0e" - integrity sha512-c+yYdCZJQrsRjTPhUx7VKkApw9bwDkNbHUKo1ovgcfDjb2kc8rLuRbIFyXL5WOEUwzSSKo3IXpph2K6DqB/KZg== - marked@^1.2.9: version "1.2.9" resolved "https://registry.yarnpkg.com/marked/-/marked-1.2.9.tgz#53786f8b05d4c01a2a5a76b7d1ec9943d29d72dc" @@ -19975,6 +19946,11 @@ marked@^2.0.1: resolved "https://registry.yarnpkg.com/marked/-/marked-2.0.1.tgz#5e7ed7009bfa5c95182e4eb696f85e948cefcee3" integrity sha512-5+/fKgMv2hARmMW7DOpykr2iLhl0NgjyELk5yn92iE7z8Se1IS9n3UsFm86hFXIkvMBmVxki8+ckcpjBeyo/hw== +marked@^2.0.3: + version "2.0.7" + resolved "https://registry.yarnpkg.com/marked/-/marked-2.0.7.tgz#bc5b857a09071b48ce82a1f7304913a993d4b7d1" + integrity sha512-BJXxkuIfJchcXOJWTT2DOL+yFWifFv2yGYOUzvXg8Qz610QKw+sHCvTMYwA+qWGhlA2uivBezChZ/pBy1tWdkQ== + math-random@^1.0.1: version "1.0.4" resolved "https://registry.yarnpkg.com/math-random/-/math-random-1.0.4.tgz#5dd6943c938548267016d4e34f057583080c514c" @@ -25368,15 +25344,6 @@ shell-quote@^1.6.1: resolved "https://registry.yarnpkg.com/shell-quote/-/shell-quote-1.7.2.tgz#67a7d02c76c9da24f99d20808fcaded0e0e04be2" integrity sha512-mRz/m/JVscCrkMyPqHc/bczi3OQHkLTqXHEFu0zDhK/qfv3UcOA4SVmRCLmos4bhjr9ekVQubj/R7waKapmiQg== -shelljs@^0.8.3: - version "0.8.3" - resolved "https://registry.yarnpkg.com/shelljs/-/shelljs-0.8.3.tgz#a7f3319520ebf09ee81275b2368adb286659b097" - integrity sha512-fc0BKlAWiLpwZljmOvAOTE/gXawtCoNrP5oaY7KIaQbbyHeQVg01pSEuEGvGh3HEdBU4baCD7wQBwADmM/7f7A== - dependencies: - glob "^7.0.0" - interpret "^1.0.0" - rechoir "^0.6.2" - shelljs@^0.8.4: version "0.8.4" resolved "https://registry.yarnpkg.com/shelljs/-/shelljs-0.8.4.tgz#de7684feeb767f8716b326078a8a00875890e3c2" @@ -27600,25 +27567,15 @@ typedarray@^0.0.6, typedarray@~0.0.5: resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777" integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c= -typedoc-default-themes@^0.12.7: - version "0.12.7" - resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.12.7.tgz#d44f68d40a3e90a19b5ea7be4cc6ed949afe768d" - integrity sha512-0XAuGEqID+gon1+fhi4LycOEFM+5Mvm2PjwaiVZNAzU7pn3G2DEpsoXnFOPlLDnHY6ZW0BY0nO7ur9fHOFkBLQ== - -typedoc-default-themes@^0.12.9: +typedoc-default-themes@^0.12.10, typedoc-default-themes@^0.12.9: version "0.12.10" resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.12.10.tgz#614c4222fe642657f37693ea62cad4dafeddf843" integrity sha512-fIS001cAYHkyQPidWXmHuhs8usjP5XVJjWB8oZGqkTowZaz3v7g3KDZeeqE82FBrmkAnIBOY3jgy7lnPnqATbA== -typedoc-default-themes@^0.6.0: - version "0.6.2" - resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.6.2.tgz#b36d8910987a40e5a80353b88e178c6ffa78f24b" - integrity sha512-+O+1aHjVIpDLsbkIDkZSNu+kutqmg7WdzahT+4KwBC/95mUgAb0xkbwdPpEJEpRX0ov1UJoCmvEPb1/VHxnTuw== - dependencies: - backbone "^1.4.0" - jquery "^3.4.1" - lunr "^2.3.8" - underscore "^1.9.1" +typedoc-default-themes@^0.12.7: + version "0.12.7" + resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.12.7.tgz#d44f68d40a3e90a19b5ea7be4cc6ed949afe768d" + integrity sha512-0XAuGEqID+gon1+fhi4LycOEFM+5Mvm2PjwaiVZNAzU7pn3G2DEpsoXnFOPlLDnHY6ZW0BY0nO7ur9fHOFkBLQ== typedoc-neo-theme@^1.1.0: version "1.1.0" @@ -27628,27 +27585,10 @@ typedoc-neo-theme@^1.1.0: lunr "^2.3.8" typedoc "~0.20.13" -typedoc-plugin-external-module-name@^2.1.0: - version "2.1.0" - resolved "https://registry.yarnpkg.com/typedoc-plugin-external-module-name/-/typedoc-plugin-external-module-name-2.1.0.tgz#25f108e99673ad34f3424719c10c299ee50e92f0" - integrity sha512-uYYe1yj6COwgyhl3Of71lkkhbEw7LVBEqAlXVvd7b9INGhJq59M1q9wdQdIWfpqe/9JegWSIR9ZDfY6mkPedJg== - -typedoc@0.15.0: - version "0.15.0" - resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.15.0.tgz#21eaf4db41cf2797bad027a74f2a75cd08ae0c2d" - integrity sha512-NOtfq5Tis4EFt+J2ozhVq9RCeUnfEYMFKoU6nCXCXUULJz1UQynOM+yH3TkfZCPLzigbqB0tQYGVlktUWweKlw== - dependencies: - "@types/minimatch" "3.0.3" - fs-extra "^8.1.0" - handlebars "^4.1.2" - highlight.js "^9.15.8" - lodash "^4.17.15" - marked "^0.7.0" - minimatch "^3.0.0" - progress "^2.0.3" - shelljs "^0.8.3" - typedoc-default-themes "^0.6.0" - typescript "3.5.x" +typedoc-plugin-remove-references@^0.0.5: + version "0.0.5" + resolved "https://registry.yarnpkg.com/typedoc-plugin-remove-references/-/typedoc-plugin-remove-references-0.0.5.tgz#08b129d2697e50208c807e06c3662fd2fc86a925" + integrity sha512-DSZ7kM/Y90CgZUKt8MiDsoi4fvrJyleHydj3ncGyqDqMdhuMes2E/4I6mSmXBrVdTjYhVH6BeoOFSbj2pQ821g== typedoc@^0.20.19, typedoc@~0.20.13: version "0.20.23" @@ -27684,6 +27624,23 @@ typedoc@^0.20.34: shiki "^0.9.3" typedoc-default-themes "^0.12.9" +typedoc@^0.20.36: + version "0.20.36" + resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.20.36.tgz#ee5523c32f566ad8283fc732aa8ea322d1a45f6a" + integrity sha512-qFU+DWMV/hifQ9ZAlTjdFO9wbUIHuUBpNXzv68ZyURAP9pInjZiO4+jCPeAzHVcaBCHER9WL/+YzzTt6ZlN/Nw== + dependencies: + colors "^1.4.0" + fs-extra "^9.1.0" + handlebars "^4.7.7" + lodash "^4.17.21" + lunr "^2.3.9" + marked "^2.0.3" + minimatch "^3.0.0" + progress "^2.0.3" + shelljs "^0.8.4" + shiki "^0.9.3" + typedoc-default-themes "^0.12.10" + typeforce@^1.11.5: version "1.18.0" resolved "https://registry.yarnpkg.com/typeforce/-/typeforce-1.18.0.tgz#d7416a2c5845e085034d70fcc5b6cc4a90edbfdc" @@ -27713,16 +27670,6 @@ typescript-tuple@^2.2.1: dependencies: typescript-compare "^0.0.2" -typescript@3.5.x: - version "3.5.3" - resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.5.3.tgz#c830f657f93f1ea846819e929092f5fe5983e977" - integrity sha512-ACzBtm/PhXBDId6a6sDJfroT2pOWt/oOnk4/dElG5G33ZL776N3Y6/6bKZJBFpd+b05F3Ct9qDjMeJmRWtE2/g== - -typescript@3.6.x: - version "3.6.4" - resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.6.4.tgz#b18752bb3792bc1a0281335f7f6ebf1bbfc5b91d" - integrity sha512-unoCll1+l+YK4i4F8f22TaNVPRHcD9PA3yCuZ8g5e0qGqlVlJ/8FSateOLLSagn+Yg5+ZwuPkL8LFUc0Jcvksg== - typescript@^3.0.3, typescript@^3.7.5, typescript@^3.8.3, typescript@^3.9.5: version "3.9.7" resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.9.7.tgz#98d600a5ebdc38f40cb277522f12dc800e9e25fa"