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?
