Skip to content
This repository has been archived by the owner on Feb 26, 2024. It is now read-only.

Configure Typedoc for @truffle/codec #2425

Merged
merged 13 commits into from Oct 17, 2019
Merged

Configure Typedoc for @truffle/codec #2425

merged 13 commits into from Oct 17, 2019

Conversation

gnidan
Copy link
Contributor

@gnidan gnidan commented Sep 29, 2019

See preview here

This PR introduces a Typedoc for the codec, as well as organizes the code a bit to make docs organization a bit easier/cleaner. Opening this as a draft, since, at least, the commits need some rebasing... or at most, we may want to continue to organize the code more before merging this.

Notes

Typedoc configuration

  • Docs are built with a forked package @gnd/typedoc right now... I forked off TypeStrong/typedoc@09a37f2 and included support export-declaration TypeStrong/typedoc#1079. Not sure if 1079 is necessary, but support for TS v3.6.x is, and that hasn't been released to NPM yet.
  • I've included the regular typedoc dependency, as this is needed by typedoc plugins. This seems to work fine.
  • I added a new "main" lib/index-typedoc.ts. This is the file that Typedoc loads to find what to document. Everything exported by that file, directly or indirectly, is considered "internal", namely... that's the public API.

Code stuff

  • I got rid of the namespaces for Types, Values, and Errors. Instead, the respective modules have been imported with name in lib/format/index.ts, and the rest of the codebase now favors importing directly from lib/format.
  • I moved a bunch of the error classes into the places where they seem to live.
  • I grouped the decoder classes into lib/interface/decoders and did a similar named re-export called Decoders.
  • I got rid of the ^Truffle prefix for those class names.
  • I haven't done anything with lib/types/decoding or lib/types/interface yet, but I think we ought to.
  • Basically, I tried to get everything organized at the public interface level, grouped into clear names. So far there's Format, Decoders, and Errors, but it'd be nice to think about how we can organize the other parts also. Note, this excludes forProject and friends... I think those should be top-level.
  • Namespaces are terrible; we should just use modules.

Considerations for work to do

  • It might be worth eliminating lib/index-typedoc.ts and just using lib/index.ts. We can use the @hidden tag to hide things manually.
  • Is there no public API for encoding yet? Will that make it into the Decoders classes? Should we rename those to account for both capabilities?
  • What's the point lib/interface? Can we make it more meaningful (like, make that the interface for real), or should we get rid of it?
  • There's probably other stuff I'm forgetting now. Let's sync up about code structure!

Other notes

  • You might want to turn off whitespace changes when viewing this PR, since the elimination of a namespace means indentation changes.
  • Harry, tell your editor to delete trailing whitespace and to add new lines to the end of files 😈

- Export named import modules in `lib/format/index`, instead of defining
  namespaces in the corresponding submodules.

- Where possible, favor importing from `lib/format` instead of submodules

- Fix some trailing line whitespaces, etc., casualties of vim
@coveralls
Copy link

coveralls commented Sep 29, 2019

Coverage Status

Coverage remained the same at 70.422% when pulling feaae80 on codec-docs into b9b4a0e on next.

- Use @gnd/typedoc for 3.6 compatibility and outstanding PR #1079
- Use typedoc module naming plugin
- Use regular typedoc for that plugin
- Remove from lib/types/errors, add to lib/allocate/storage
- Also remove an unused import
- Update lib/index to reflect new location
New home! lib/decode/errors!
i.e. ContractBeingDecodedHasNoNodeError and ContractAllocationFailedError

- Update usage accordingly in lib/interface/contract
- Export in lib/interface/index
- Wrap in `Decoders` namespace for export in lib/interface/index
- Mark constructors as private
- Rename Truffle*Decoder to just *Decoder
- Add usage
- Group format into Format module
@gnidan gnidan marked this pull request as ready for review October 14, 2019 12:26
Copy link
Contributor

@haltman-at haltman-at left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Basically just rubber-stamping this, we can review the rearrangements when coalescements is PR'd.

@gnidan gnidan merged commit 017c42f into next Oct 17, 2019
@gnidan gnidan deleted the codec-docs branch October 29, 2019 15:40
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants