Review/std.serialization

Description

std.serialization is a package authored by Jacob Carlborg and based on his Orange library. It enables saving any D data type to customizable format (using "archiver") and loading it back from serialized input.

Related links

Discussion of possible range interface

Current state

This package has been under several reviews and is still being updated to match last comments

Review 1

Result

voting delayed, needs improved proposal integration in Phobos

Description

Review thread

Lot of discussion during the first review was about stripping Orange of non-Phobos dependencies and adapting it as part of Phobos source tree. It has pretty much ended with consensus that more integrated source needs to be provided before further review.

Review 2

Result

voting delayed, critical design issues need to be addressed

Changelog

   - Sources has been integrated into Phobos source tree
   - DDOC documentation has been provided in a form it should look 
     like on dlang.org
   - Most utility functions/template code depends on have been 
     inlined. Remaining `package` utility modules:
       * std.serialization.archives.xmldocument
       * std.serialization.attribute
       * std.serialization.registerwrapper

Description

Review thread

This time discussion was more focused on specific API decision and choices that need to be made before approval. Most important blocker was identified as lack of range-based interface that will fit into existing Phobos approach.

Other critical comments:

1. Lack of simple practical examples to catch up fast
2. Lack of clear definition of package goals and use cases
3. Should use recent `documented unitttest` feature
4. pre-UDA API should remain in Orange
5. several naming and styling comments
6. unclear requirements for binary archives (aka strict serializing vs permissive with reordering)
7. should provide simple procedural wrappers for common operations
8. Serializable interface too inflexible (and related functionality)

Lack of Phobos guidelines that needs to be addressed by upstream:

1. Placement of package-wise / functional tests
2. Placement of package-wise documentation / examples (package.d ?)

Jacob plans after review

   My todo list looks like this:
       - write an overview documentation
       - improve the documentation for std.serialization.serializable to 
         indicate it's not required
       - implement a convenience function for serializing
       - implement a convenience function for serializing to a file
       - remove Serializeable
       - check only for "toData" when serializing
       - check only for "fromData" when deserializing
       - split Serializer in to two parts
       - make the parts structs
       - possibly provide class wrappers
       - split Archive in two parts
       - add range interface to Serializer and Archive
       - rename all archives to archivers
       - replace ddoc comments with regular comments for all package protected 
         symbols