[Request] 🚀 Better API documentation

[KL13NT]

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.

[dai-shi]

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.

[Saulius-HALO]

@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?

[dai-shi]

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?

It will create a store only when create is called.
useStore doesn't create a new store.

[dai-shi]

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?

[darkocejkov]

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.

[dai-shi]

@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?

[darkocejkov]

@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!

[dai-shi]

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.

[dbritto-dev]

@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

[dai-shi]

I don't think we need to wait for v5. API doesn't change. v5 may take a long time.

[dbritto-dev]

@dai-shi in that case I would like to help to kick out v5 as soon as possible

[dai-shi]

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.

[charkour]

@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.

[dai-shi]

reopening this.

[dbritto-dev]

Hey peeps I'm going to retake this

[dbritto-dev]

Hi folks, some news I'm working on revamping docs but on my repo until is done -> dbritto-dev#1, btw you can follow the discussion here -> #2489