std.serialization: pre-voting review / discussion

[Dicebot]

Ok, I was trying to avoid expressing personal opinion until now 
and mostly keep track of comments of others but now that I have 
started reading docs/sources in details, will step down from 
review manager role for a moment and do some very subjective 
reviewing :)

-----------------------

Hot topic first. Ranges. As far as I can see it it is not about 
"lets stick range API whenever possible because it is the way 
Phobos does things". Key moment here to recognized use cases that 
are likely to require range-based interface and focus on them.

As far as I can see it there two important places where 
possibility for range-based API can be helpful - providing values 
for serialize and providing raw data to deserialize, as well as 
matching Archiver changes.

Former is relatively trivial - "serialize" should have an 
overload that accepts InputRange of monotyped values to take care 
of and provides ForwardRange as a result, which serializes values 
one-by-one lazily. Same goes to archiver.

Latter is a bit more interesting. It would have been cool if 
instead of accepting raw data chunk that matches deserialized 
object size serializer.deserialize could have accepted InputRange 
that provides sequence of any random chunks of raw data and use 
it to construct values on per-request basis, lazily. This will 
require maintaining a buffer that will keep unconsumed remainder 
of the last chunk and make some decisions about behavior in case 
of hitting "empty()" before getting enough data to deserialize 
object.

But it is not be something you should care about right now 
because only actual function/method signatures are needed with 
static asserts insides, actual implementation can be added later 
by anyone willing to spend time.

-----------------------

Now about my personal feeling about std.serialization as a 
potential user. Core functionality I'd like to see in such module 
is the ability to dump D data type state into arbitrary formats 
in a robust way that requires minimal interference from the user 
code. Something like what is done with toJSON/fromJSON in vibe.d 
API stuff but more generic when in comes to output formats and 
more robust when it comes to data hierarchies to load/store.

Judging by examples and documentation this is exactly what 
std.serialization does and I like it. It lacks some better output 
(Archiver) choices but it is more like Phobos fault.

What I really don't like is excessive amount of object in the 
API. For example, I have found no reason why I need to create 
serializer object to simply dump a struct state. It is both 
boilerplate and runtime overhead I can't justify. Only state 
serializer has is archiver - and it is simply collection of 
methods on its own. I prefer to be able to do something like 
`auto data = serialize!XmlArchiver(value);`

That is not something that would have made me vote against the 
inclusion (I think it is much needed anyway) but that may have 
discouraged me from using this part of Phobos and fall to some 
NIH syndrome.

I have found documentation complete enough to get a basic 
understanding personally but one thing that has caused some 
frustration is that docs don't make clear distinction between 
minimal stuff and extra features. For example, there is 
https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_serializable.html 
- my guess that it is only used if user wants to override default 
serialization method for an aggregate type. But documentation for 
it is written in such manner that it gives an impression that it 
is absolutely required.

-----------------------

Last thing is not really relevant but is more about general 
documentation problem. This may be the first package that makes 
use of new "package.d" system and it shows that we need some way 
to provide package-wide documentation to keep things clear. I 
guess for DDOC itself generating output from package.d is nothing 
special - but what about dlang.org? How hard will it be to update 
a documentation page to support own block for package roots?