[Feature Request] Can you please add sort of explanation / documentation?

[matthew-dean]

This library and set of data structures looks very promising. But... please imagine that your users do not all have PhDs in data structure theory. Can you provide in your docs a set of explanations of how each data structure differs and some typical use cases?

For example, say I want to build a tree that has a single root, but multiple nodes (branches) from each node, and I want to be able to traverse from the bottom of a branch back up to the root. I've crawled through these docs several times and while some classes have brief descriptions, not all do, and there's not always a clear delineation for what use cases are covered or not covered, or why one might use one data structure over another. It feels really difficult to find a data structure in this library that has the smallest footprint, but meets my particular needs. There's a page that has tests, but it doesn't demonstrate what code is actually running, or what the data structure is supposed to represent, or if it illustrates in any way the limitations of what that data structure can represent, so I fail to see how these tests are useful whatsoever. It just puts some colorful blobs on the screen and then sometimes removes colorful blobs.

There's obviously a lot of careful work / engineering that's gone into these data structures and APIs, so I don't want to knock that effort at all, but it feels like there's a vast communication gap that prevents an average or even advanced engineer (if they don't understand the entirety of data structure theory) from being able to use this library.

Is there... maybe a 3rd-party site that offers guidance in the mental models of which data structures do what?

[zrwusa]

This library and set of data structures looks very promising. But... please imagine that your users do not all have PhDs in data structure theory. Can you provide in your docs a set of explanations of how each data structure differs and some typical use cases?

For example, say I want to build a tree that has a single root, but multiple nodes (branches) from each node, and I want to be able to traverse from the bottom of a branch back up to the root. I've crawled through these docs several times and while some classes have brief descriptions, not all do, and there's not always a clear delineation for what use cases are covered or not covered, or why one might use one data structure over another. It feels really difficult to find a data structure in this library that has the smallest footprint, but meets my particular needs. There's a page that has tests, but it doesn't demonstrate what code is actually running, or what the data structure is supposed to represent, or if it illustrates in any way the limitations of what that data structure can represent, so I fail to see how these tests are useful whatsoever. It just puts some colorful blobs on the screen and then sometimes removes colorful blobs.

There's obviously a lot of careful work / engineering that's gone into these data structures and APIs, so I don't want to knock that effort at all, but it feels like there's a vast communication gap that prevents an average or even advanced engineer (if they don't understand the entirety of data structure theory) from being able to use this library.

Is there... maybe a 3rd-party site that offers guidance in the mental models of which data structures do what?

Thank you very much for your feedback. Indeed, as you mentioned, we should consider as many user groups as possible. In the next version, we will add some usage explanations and common use cases for each data structure, and describe memory usage. If necessary, we will provide a table. I believe your suggestions will help make this library accessible to a wider range of users.