Documentation

[LeonMontealegre]

Proper documentation is desperately needed, I am currently working on it but it should be officially documented (pun intended) as well.

Tasks:

• [x] Create site
• [x] Auto-generated JSDocs
• [x] Full "wiki" copy-over
• [ ] Flow diagrams for the project
• [ ] Style Guide
• [ ] Explanations for larger systems like Actions, Tools, Redux, etc.
• [ ] API documentation
• [x] Stream-line publishing the doc-site (Github Actions)
• [x] Design Docs

From PR #684 :

Known issues:

• [ ] Parameters/Returns don't properly apply markdown in the description
• [ ] Handling of abstract methods/classes
• [ ] Handling of interfaces
• [ ] Handling of type declarations
• [ ] Handling of extends/implements
• [ ] Optional parameters
• [ ] Handling of exported closures/variables (tools/constants/etc)
• [ ] no support for site/
• [ ] static class variables
• [ ] Some docs have lots of any and boolean as true | false (DigitalWire) [presumably due to circular dependency hell)
• [ ] Destructured parameters
• [ ] Map/Record/Partial handling

Planned features:

• [ ] Auto-rebuilding of docs
• [ ] Type-linking should link with #TypeName as well (in the URL)
• [ ] Auto-publishing to doc site

Need to test:

• [ ] Unions + intersections (should work though)

(extra todo: UML diagrams, (see Demopans discord chat leon))

[TGCrystal]

Another potential type of documentation to consider adding: some kind of "exit docs" that someone could fill out if they are in the middle of working on something, but the semester is about to end and they don't plan on continuing working on OpenCircuits after that. They could explain what branch the work is on, what work has been done, and what work is still left to do.

[TGCrystal]

I noticed while creating jsdocs in #630 that the throws and see tags do not show up in the auto-generated jsdocs. Not sure if that was an intentional omission, I messed something up/didn't see it, or it wasn't yet implemented, but I think those should also should show up in the generated documentation.

[LeonMontealegre]

Note for myself: Could be cool to have any documentation-changing PRs get published onto a sub-url of the docs site like: docs.opencircuits.io/pull/### so that it can be viewed without having to manually checkout and run the docs server

[TGCrystal]

• [ ] Add support for tuples (see here)