View source for Review/std.serialization

== Description ==

[https://github.com/jacob-carlborg/phobos/tree/serialization std.serialization] is a package authored by Jacob Carlborg and based on his [https://github.com/jacob-carlborg/orange Orange] library. It enables saving any D data type to customizable format (using "archiver") and loading it back from serialized input.

=== Related links ===

[http://forum.dlang.org/post/kv31ss$14cc$1@digitalmars.com 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 ===

[http://forum.dlang.org/post/adyanbsdsxsfdpvoozne@forum.dlang.org 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 ===

[http://forum.dlang.org/post/hsnmxykmoytfvwroikzk@forum.dlang.org 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:

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

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

# Placement of package-wise / functional tests
# 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