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.
