Effect-TS / effect

An ecosystem of tools to build robust applications in TypeScript
https://effect.website
MIT License
7.69k stars 244 forks source link

Better jsdoc documentation #3695

Open roninjin10 opened 1 month ago

roninjin10 commented 1 month ago

What is the problem this feature would solve?

I find using Effect to be extremely painful for getting into a flow state. The reason for this is because I consistently need to leave my editor to figure out really basic usage information usually to search the docs or source.

This becomes more painful when using more niche libraries like effect/rpc.

With better jsdoc documentation this wouldn't be a problem.

What is the feature you are proposing to solve the problem?

Investment into JSDoc documentation complete with @example and links to the actual documentation.

What alternatives have you considered?

I have attempted to use AI as the answer to this problem but AI hallucinates or uses old APIs with Effect so much it's counter productive

nounder commented 1 month ago

What really helps me is having Effect repo open in another window to peek at the code and tests. Granted, I read the whole documentation and this may be a requisite to understand the source code itself.

tmcw commented 1 month ago

I very strongly agree with this issue - a lot of Effect's APIs have zero JSDoc annotations and it makes it way harder to learn, and brings back bad memories of functional programming libraries that rely so heavily on their type signatures and have very little written documentation. Even commonly-used stuff like Effect.fail doesn't have anything at all in the API documentation written about it.