zustand
zustand copied to clipboard
pmndrs
[Request] đ Better API documentation
Description
The source code lacks proper API documentation for the internal methods available, limiting contribution.
Context
It seems to me that the code lacks proper documentation, making contribution harder. I tried to create my own zustand-like store/hooks in an experiment project I'm working on (I'm trying to not use libraries) but I failed. When I came over to the repo to inspect the code and follow along I was greeted by a lot of TS (I'm coming from a Vanilla JS background), none of the internal methods had proper documentation at all.
I tried to follow with how the code works but there are just too many imports/exports, TS type declarations, and internals that are hard to follow without actual explanation of their behaviour/role. This makes reading and following along the code harder, thus limiting contribution.
Request
A few JSDoc-like comments would be a huge help. All I need is a reference of sorts to know which methods do what. I don't wanna sound like it's a "must", I just need such documentation. I would create a PR for this if anyone's willing to guide me around as well.
I can answer some questions if you ask me specifically here. Please don't ask many things at once. Let's start with a few important ones for you.
@dai-shi Hello,
export const useStore = create(...
Does this create a new store instance every single time when const state = useStore(); is used? If so any suggestions how to properly mitigate it in react? Use providers or something?
export const useStore = create(...Does this create a new store instance every single time whenconst state = useStore();is used? If so any suggestions how to properly mitigate it in react? Use providers or something?
It will create a store only when create is called.
useStore doesn't create a new store.
Hi folks, Please allow me to close this issue as stale. It's not very actionable and at least some developers have no issues reading the code and making contributions.
@Saulius-HALO If you need more help, would you please open a new discussion?
Apologies, but that doesn't satisfy me at all. Zustand is SO great but the lack of even a simple API reference makes it much harder to use idiomatically, especially when in conjunction with other packages. I would highly recommend even the simplest technical reference, as it's much more difficult to answer specific questions in a discussion board for both any maintainers and developers using Zustand.
@dbritto-dev @charkour Any idea for API docs or a technical reference?
@darkocejkov Do you have any example in other projects that provides what you expect?
@dai-shi Of course! Some of my favorites I've used are:
- React Query
- React Hook Form
- Material UI
- Especially because the main component pages are mostly around examples, while also including really detailed API references, like this one specifically about a button component.
Essentially, what I would like to see is more of a technical detail to what functions return, what is expected for arguments, etc. Kind of like a type declaration file but less bogged down by complex types. Thank you for replying by the way, I appreciate it very much!
I see. I thought it's more about internal things. But they are more like usage docs. I'm pretty sure @dbritto-dev @charkour and others can help on it.
@dai-shi yeah, I've been thinking on that a lot and I guess we can add it to v5 since we are cleaning the API. any thoughts @charkour? I would like to help with that
I don't think we need to wait for v5. API doesn't change. v5 may take a long time.
@dai-shi in that case I would like to help to kick out v5 as soon as possible
It's not blocked by our effort. I would like to get as many feedback as possible before the final release. That's what I learned from v4. And, it should not stop improving docs.
@dbritto-dev, you can lead the docs efforts and I would be happy to help. However, the readme documentation is sufficient in my opinion, I don't yet understand the benefits of making usage docs different than what we have on the readme and other markdown files.
Hi folks, some news I'm working on revamping docs but on my repo until is done -> https://github.com/pmndrs/zustand/pull/2508, btw you can follow the discussion here -> https://github.com/pmndrs/zustand/discussions/2489
@dai-shi ć莥ĺćŻćçśćçćŹĺ°ĺĺďźç¸ĺ˝äş useReducer ĺč˝ă çŽĺ create ćŻĺ ¨ĺąĺŻä¸çäźćĺžĺ¤ĺąéć§
