improving docs by adding examples

[mh-cbon]

Hi!

I was reading at last changes, great. However, since the beginning i think the documentation is lacking clarity.

I would like to propose a pr to add examples likes this one https://golang.org/src/io/io_test.go#L350
Attached to method, and easy to access from godoc.

I m not sure which godoc engine is running https://godoc.org/github.com/timshannon/bolthold and if it is the same as https://golang.org/pkg/bytes/ but i believe that it will be updated so even if it does not display today, it will tomorrow.

[timshannon]

Yep, that's definitely something I can do. Until I get around to it, there are examples of every query type
in the _test.go files.

For example: https://github.com/timshannon/bolthold/blob/master/find_test.go

[justinfx]

I've been trying to get started with Bolthold today, but the lack of documentation has me stuck on properly understanding a custom Storer implementation and how the index name relates to the index query behavior. So an example of that would be awesome. My goal was to index a computed value for a few different fields in a custom index but maybe that isn't possible and I need to precompute a hash and store it as a field with an index?

I don't really understand what this is doing:
https://github.com/timshannon/bolthold/blob/master/find_test.go#L290

For now I am just going to only use tagged indexes on fields and use the same index name as the field, until I can understand how this works.

[timshannon]

If you pass in a Go Type that implements the Storer interface, it'll use your implementation rather than the built-in implementation that uses reflection, which I call AnonStorer. That returns byte arrays that represent index values based on the default BoltHold struct tags.

type Storer interface {
	Type() string                        // used as the boltdb bucket name
	Indexes() map[string]Index           // [indexname]indexFunc
	SliceIndexes() map[string]SliceIndex // [indexname]sliceIndexFunc
}

// Index is a function that returns the indexable, encoded bytes of the passed in value
type Index func(name string, value interface{}) ([]byte, error)

// SliceIndex is a function that returns all of the indexable values in a slice
type SliceIndex func(name string, value interface{}) ([][]byte, error)

So if you wanted to compute the value of an index. You just need to implement those 3 methods on your type that you want to store in Bolthold.

And yes, there isn't a lot of documentation on this. I consider it more advanced, and not necessarily what most people would do, but the option is there if you want complete control over how BoltHold indexes your Type.

[justinfx]

Thanks @timshannon for the reply. Sure, I gleaned that much from the description and having a play with implementing it. I am still in the middle of testing it. But I wasn't clear on the name value as it seems I should just ignore it when writing my own implementation as I know the field, or maybe its not related to a specific field. The latter is most confusing to me, since I don't really understand how using the index in the query relates to an index that isn't specific to a field name, such as an index that is a hash of 4 fields. An example of a Storer would be great, since the code for AnonStorer specifically only relates to a field value.

[justinfx]

Another example of where it is confusing to use a custom Storer without an example is that I seem to be sometimes receiving a *Item and sometimes receiving a **Item into the Index function. The builtin AnonStorer seems to cope with it fine through reflection conditionals. But in my case I panic from the type assertion. Seems to come from an upsert when it deletes an existing index and it just creates a new pointer of the original type (*Item) which ends up being a **Item.
Anyways, just one example of where I am confused without an example of really how to handle the parameters of the Storer index function.

[timshannon]

Yeah, there might be some bugs in your use case. Feel free to open up a separate issue if you find something. When I get a chance, I'll add a full test scenario / example of writing your own Storer based type. I'm betting that'll expose a few issues that the AnonStorer glosses over by the nature of having to handle whatever a user passes in.