improve document docs

[PSeitz]

No description provided.

[adamreichold]

I think it would be helpful to explain what these bring to the table, i.e. how the three built-in options compare, e.g. BTreeMap provides associative access but ordered where HashMap has faster associative access, but neither supports multiple values per field if I understand this correctly.

[PSeitz]

Yeah, not sure why we have that actually. Seems too niche

[ChillFish8]

I wrote the original doc originally IIRC, but the motive for the impl was because a lot of people have situations where they have single-value fields and just want to deserialize and serialize the data to and from JSON as is without needing to convert the by-default multi-value fields into single-value fields. So this was a utility for that.

[adamreichold]

One other question I had while trying to migrate my code base to this and which I think would be nice to clarify in the docs: Can I rely on DocumentDeserialize visiting my fields in the same order they were serialize into the document store?

If I cannot match field positionally between serialization and deserialization, I would need access to the relevant Field values when deserializing a structure field by field, i.e. something like DeserializeSeed to pass in a collection of Field values.

[PSeitz]

One other question I had while trying to migrate my code base to this and which I think would be nice to clarify in the docs: Can I rely on DocumentDeserialize visiting my fields in the same order they were serialize into the document store?

If I cannot match field positionally between serialization and deserialization, I would need access to the relevant Field values when deserializing a structure field by field, i.e. something like DeserializeSeed to pass in a collection of Field values.

From the API contract there is no such guarantee, e.g. we may choose whatever is better compressible in the future.

[adamreichold]

From the API contract there is no such guarantee, e.g. we may choose whatever is better compressible in the future.

But then we need to extend the API with a seed as otherwise, I do not see how I can deserialize the compile-time fields of struct without knowing their runtime field ID.

[adamreichold]

From the API contract there is no such guarantee, e.g. we may choose whatever is better compressible in the future.

But then we need to extend the API with a seed as otherwise, I do not see how I can deserialize the compile-time fields of struct without knowing their runtime field ID.

#2362 should provide what is required pass the runtime field ID to a deserialize implementation.