Truffle: Finish preparing @truffle/codec and @truffle/decoder for release

Created on 29 Oct 2019 · 10Comments · Source: trufflesuite/truffle

Issue

Part of #2191, this issue seeks to gather known work remaining for the upcoming releases:

@truffle/codec v0.1.0 (new package)
@truffle/decoder v4.0.0 (major, breaking)

This issue should represent that which is blocking release, generally related to interface concerns and documentation. This issue constitutes outstanding tasks listed in #2485 and #2467, as well as from informal discussion.

ℹ️ Docs preview
_(current as of bf4a50389e7989501090ebdbae3e287015e9842c)_

Tasks

Docs

[x] Determine permalink URL for codec docs (#2549)
[x] ~Expand on bulleted list of entry functions with additional figure that provides at a glance for which decode methods are available via which entry functions.~
[x] Ensure completeness of module comments / interface comments / etc. (anything that gets its own page). (_These can be minimal in most cases_)

Style notes: most comments are written in subject-dropped indicative mood, where the subject is the module in question (probably best to follow that convention)
[x] Put giant warnings on nativize docs (and nativizeVariables, naturally)
[x] Review docs for usage of TypeDoc categories to group index listings.

Note on usage: @category must be added to the symbol declaration; marking the export doesn't work
[x] Edit values-vs-errors distinction to mention overlong arrays / overlarge pointers
[x] Consistify private vs. hidden: everything that is marked either private or hidden should be protected instead.
[x] Fork typedoc theme and update default to include only public, exported identifiers
[x] Finish various docs entrypoints
- [x] Author packages/codec/README.md (codec repository readme)
- [x] Author packages/decoder/README.md (decoder repository readme)
- [x] Author _Truffle Decoding and Encoding_ index documentation
- [x] Do a once-over for @truffle/decoder index documentation
- [x] Author @truffle/codec index documentation
- [x] Move Format documentation and author overview section
[x] Add usage notes/example for ResultInspector
[x] ~Determine feasibility of modifying the TypeDoc theme's display of async functions (to differentiate them more clearly from regular functions~
[x] Find home for notes on decoding modes and ensure it's linked to appropriately.

Interface changes

[x] Define in-house interfaces for Transaction and Log
[x] Simplify return type for decodeTransaction / decodeLog
[x] Ensure Truffle-at-large only ever imports @truffle/codec and never a submodule
- [x] Find home for allocate/types
- [x] Double check that there are no others
[x] Finish exporting Codec.*.{Allocate|Decode|Encode} as appropriate
[x] Question: Should state() return a ContractValue, after appropriate changes to the type? (@haltman-at's current thinking: No)
[x] Question: Should contractKind be a mandatory field on ContractType? (@haltman-at's current thinking: No)
[x] Make protected methods use additionalContexts argument, so public methods exclude mention of internal argument.
[x] Split up read, and make bytes to contain read/bytes as well as parts of what's currently in decode/basic
[x] Move Constant to own data location instead of being part of Ast
[x] Import ContractObject as a different identifier (TruffleArtifact maybe?)

Other cleanup

[x] Check for unnecessary dependencies and devDependencies in package.json

Docs Epic Task codec

Source

gnidan

All 10 comments

Note: I'm hoping my new docs written for redo-interface address point no. 2 somewhat.

haltman-at on 29 Oct 2019

Claiming the protected and nativize points.

haltman-at on 29 Oct 2019

Took a look at it, and I'm calling "Determine feasibility of modifying the TypeDoc theme's display of async functions (to differentiate them more clearly from regular functions" out of scope because of difficulty

gnidan on 30 Oct 2019

OK. What do you think of me going through and just manually marking all the async functions with bold notices?

haltman-at on 30 Oct 2019

👍1

I added "Add usage notes/example for ResultInspector" since there's nothing there now, but we probably need something, since we point users in that direction.

gnidan on 4 Nov 2019

👍1

I added "Add usage notes/example for ResultInspector" since there's nothing there now, but we probably need something, since we point users in that direction.

OK, I can add those.

haltman-at on 4 Nov 2019

🚀1

Docs will have permanent URL at https://www.trufflesuite.com/docs/truffle/codec

gnidan on 5 Nov 2019

Just wanted to document where and how Web3.js is used within @truffle/decoder (@truffle/codec only uses web3-utils which is relatively lightweight). The intention is to find out how coupled we are with Web3.js and whether or not it is feasible to decouple from it.

Based on commit 98ae40e3ef2ee729f1d5d227dcb0ea92b90db60d.

`utils.ts`

Line 141:
```
Web3.utils.toChecksumAddress(value);
```

`index.ts`

Line 156 the Provider constructor from Web3.js is used:
```
import { Provider } from "web3/providers";
```
Line 231 the forContract() function accepts a variable contract where it expects a nested web3 object to grab the currentProvider:
```
return await forArtifact(contract, contract.web3.currentProvider, artifacts);
```

`types.ts`

The structure of the following interfaces are informed by Web3.js object structures:
- Log
- DecodedLog
- Transaction
Line 255 the ContractConstructorObject interface includes a web3 instance inside of it.