Decide how to document cht-datasource

[m5r]

Describe the issue
Adjacent to #9065, we should set up some form of docs early on. It doesn't have to be part of the first PR necessarily but it should be taken care of sooner rather than later. This shared library will eventually become large enough that it will be difficult to know where is what just from reading the code and we might run into road bumps if we delay documenting it too much. Ideally the docs would be generated from the code with some examples we could add to showcase how to use functions.

Describe the improvement you'd like
The top contender to get us there is TypeDoc, it generates this type of API documentation from the code and its TSDoc.
For example this is evolu's useQuery docs and here is what it was generated from.
TypeDoc comes with a default theme but if we ever feel fancy we can customize it to be more on brand with the CHT.

Describe alternatives you've considered
https://github.com/Effect-TS/docgen but it seems very basic

[garethbowen]

Another option is jsdoc which we already use: https://github.com/medic/cht-core/blob/master/scripts/build/build-documentation.sh

Whatever solution we choose here should be consistent with the existing docs so it's a single solution for all documentation.

[jkuester]

It looks like TSDoc is just a superset of the JSDoc standard and TypeDoc is compatible with JSDoc comments. Perhaps that means it would be trivial to just use TypeDoc to generate all the docs (both our existing JSDocs from the JS files and the new TSDocs from the TS files)? That looks like the cleanest way forwards to me since we could take advantage of TSDoc (while still gradually migrating things from JSDoc). Very similar to our overall code strategy here anyway...

That being said, y'all just say the word and I will rewrite this whole library, top to bottom, using effect-ts! I love that library! 🤣 🚀

[m5r]

using effect-ts

Not to diverge from the original issue but effect-ts reminds me a lot of RxJS and it's one of the things I wish we didn't use in webapp 🥲

[jkuester]

Yeah, I do not have a ton of experience with RxJS, but I do think it solves some of the same challenges as Effect. If I had to guess, I think Effect has a broader scope and wants to be more of a "standard library" vs just providing "Observable" async functionality (also it is TS-native). Effect bills itself as being more of a spiritual successor to fp-ts.

Either way, I would be very interested to chat with you sometime about your thoughts on RxJS and its strengths/weaknesses! (And to be extra clear, I am not seriously suggesting we incorporate Effect into the cht-core code base. 😓 It is a cool library, and has been a lot of fun to learn, but it is basically like learning a whole new language (especially if you are like me and have not done my FP-style coding before....).