RFC: enhance (de)serializers options description

[Totktonada]

We have three public (de)serializer modules: msgpack, json and yaml. Also I guess we'll make msgpackffi module public as possibly more performant alternative to msgpack module when we'll make its behave it exactly as msgpack (see tarantool/tarantool#4499).

All three (four) modules have different applicable settings (see also tarantool/tarantool#4622) and it would be simpler to understand them if they would be described for each module separately. Now it is described once on json module page and linked from msgpack and yaml pages.

Maybe there other ways to organize the information about all those options. I'll don't mind against any other way that will give enough information for a user.

The table of supported options (gathered from 2.3.0-206-ge68665503 source code):

option \ (de)serializer	msgpack	msgpackffi	json	yaml
encode_sparse_convert	+		+	+
encode_sparse_ratio	+		+	+
encode_sparse_safe	+		+	+
encode_max_depth	+	+	+	N/A(1)
encode_deep_as_nil	+	+	+	N/A(1)
encode_invalid_numbers	+		+	+
encode_number_precision	N/A(2)	N/A(2)	+	+
encode_load_metatables	+		+	+
encode_use_tostring	+		+	+
encode_invalid_as_nil	+		+	+
decode_invalid_numbers	+		+	+
decode_save_metatables	+	+	+	+
decode_max_depth	N/A(3)	N/A(3)	+	N/A(3)

(1) YAML supports references, so cycles can be encoded and there are much less reason to support a depth boundary.
(2) MsgPack encodes 32/64 bit floating point values w/o a precision loss; JSON and YAML support this option, because they are text formats and format numbers in human-readable way.
(3) Don't know a reason.

Empty cells in msgpackffi column is the subject to support in the scope of tarantool/tarantool#4499

[Totktonada]

We discussed this issue with @Onvember. To sum up: it seems the main problem with this list of options is lack of proper descriptions rather then describing them all in context of json module.

Example: encode_load_metatables is described as 'load metatables'. A user may think that an MsgPack extension type is used to store both table and its metatable (it is 'load', not 'store', but it is 'encode', right?). But how functions in the metatable are encoded? Using string.dump? So, those function should not capture upvalues?

However the option is not about this: it just shows on __serialize field in a metatable (if exists). The possible values are:

• A string: 'array', 'seq', 'sequence', 'map', 'mapping' ('seq' and 'map' have special meaning for yaml module and means using of flow style). It allows a user to choose a representation of an empty or a sparse array as an array or as a map.
• A function, which returns a representation a user want to see after serialization. It is especially useful for cdata and userdata (and maybe useful for Lua tables to, say, hide logically private fields).

As we see, it worth to describe it more then just 'load metatables'. Even the description above it not enough, I think: we should give proper examples, which will show how a behaviour changes depending on an option (maybe in different cases). The same is applicable for other options.

Please, ask for more information is something is not clear, look over tests in tarantool and experimenting youself to understand the behaviour.

We also discussed it with @lenkis and she propose to move (de)serializer options description to its own section. I think it is less important then good descriptions itself (despite I proposed this above), but is also good change. It looks appropriate to move this list into its own section of app server guide.