Better source comments/documentation in packages

Describe the problem

Familiarizing myself with the internal package source code has been frustrating. Some of the more complex functions can be fairly opaque. The JSDoc type declarations are useful, but it seems like a missed opportunity to be using them exclusively as type declarations when we could add more descriptive information. I understand that investing too heavily into internal documentation pre-1.0 might cause some headaches if there are significant changes to the codebase, but I think the benefits probably outweigh that.

Describe the proposed solution

• Add basic descriptions to JSDoc annotations. Short function and parameter descriptions like the ones described on the JSDoc website are probably all this needs.
• [nice to have] Configuration for JSDoc site generation to create some human-readable docs for development purposes.
• Add some instructions for updating the JSDoc descriptions to CONTRIBUTING.md

Alternatives considered

Wait until 1.0 release, when more stability can be expected for the internal packages.

Importance

nice to have

Additional Information

I’m happy to work on this incrementally as I go through the codebase and learn how it all works.

[benmccann]

Yeah, I agree with all that

[JEbertPrime]

I’ll open up a PR for some small changes just to hammer out the process and reference this issue