std.serialization: pre-voting review / discussion

[Walter Bright]

On 8/20/2013 6:28 AM, Jacob Carlborg wrote:
> 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.

You can hide comments from ddoc by not starting them with /** but with /*

> 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

Hmm. That looks then like a ddoc bug.


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

Doesn't make sense to me. I would think the archive would be what is created, 
not the creator.

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

What confuses me here is the conflation between the archiveR and the resulting 
archive, i.e. "an archiver creates an archive". Saying "archive creates the 
archive" is a bit of a disastrous conflation of the terms, as it makes the 
documentation a constant source of confusion.


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

Some exposition of this is necessary, along with some comments along the line 
that the package provides a generic archiving interface, and a couple 
implementations X and Y of that interface, and that other implementations such 
as Z, the zip archiver, are possible.