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
