std.serialization: pre-voting review / discussion

[Jacob Carlborg]

On 2013-08-20 10:01, Walter Bright wrote:

> 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.

Yes, I need to add some overview documentation. There's still the 
problem of finding the overview.

> 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
> ----------------

Hehe, yeah :)

> https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_registerwrapper.html
>
>
> Lacks an illuminating example.

That doesn't need to be ddoc comments at all. The whole module is 
declared "package". I would be really nice if ddoc could automatically 
hide anything that wasn't public or protected but still generate the 
documentation for package and private.

> https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_serializer.html
>
>
> When would I use a struct Array or a struct Slice?

Same as above. I'll see if they really have to be public.

> 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.

Same as above.

I have used lower case because I don't consider this a struct, yes 
technically it is. This is an attribute (UDA) and I think attributes 
should be lower case. Or rather it's supposed to be used on types to 
indicate they are UDA's:

@attribute struct foo {}

The reason for this is that I'm a bit disappointed in the implementation 
of UDA's in D. I would have liked to have some kind of entity that I can 
point to and say "this is an attribute". Currently all random values and 
types can be used as an UDA, I don't like that.

Same idea why to have "interface" and "abstract" keywords. It's possible 
to avoid these, i.e. C++, but I think it's a lot better to have them.

> https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_archives_archive.html
>
>
> Aren't interfaces already abstract? I.e. abstract is redundant.

I have no idea why "abstract" is added there. The definition looks like 
this:

https://github.com/jacob-carlborg/phobos/blob/serialization/std/serialization/archives/archive.d#L88

> The documentation defines an archive more or less as an archive. I still
> don't know what an archive is.

"The archive is the backend in the serialization process."

And

"The archive is responsible for archiving primitive types in the format 
chosen by the archive implementation. The archive ensures that all types 
are properly archived in a format that can be later unarchived."

> (E.g. a zip file is an archive - can this create zip files?)

Theoretically one can create an archive that serializes to a zip file, 
yes. Or rather the format used by zip. An archive shouldn't write to disk.

-- 
/Jacob Carlborg