std.serialization: pre-voting review / discussion

[Walter Bright]

On 8/12/2013 6:27 AM, Dicebot wrote:
> Documentation:
> https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/index.html

Thank you, Jacob. It looks like you've put a lot of nice work into this.

I've perused the documentation, and all I can think of is "What's a cubit?"

http://www.youtube.com/watch?v=so9o3_daDZw

I.e. there are 9 documentation pages of details. There's no obvious place to 
start, no overview, no explanation of what serialization is for and why I might 
want to use it and what's great about this implementation. At least none that I 
could find. Also needs some non-trivial canonical example code.

Something that answers who what where when why and how would be immensely useful.



Some nits:

https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_serializationexception.html

Something went horribly wrong here:
----------------
Parameters:
Exception exception the exception exception to wrap
----------------

https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_registerwrapper.html

Lacks an illuminating example.

https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_serializer.html

When would I use a struct Array or a struct Slice?

https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_attribute.html

struct attribute should be capitalized. When would I use an attribute? Does this 
have anything to do with User Defined Attributes? Need a canonical example.

https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_archives_archive.html

Aren't interfaces already abstract? I.e. abstract is redundant. The 
documentation defines an archive more or less as an archive. I still don't know 
what an archive is. (E.g. a zip file is an archive - can this create zip files?)