On Tuesday, 13 August 2013 at 15:04:38 UTC, Jacob Carlborg wrote:
> I worked quite hard with the documentation. There are code examples here as well, I just don't know where to put them in Phobos:
>
> https://github.com/jacob-carlborg/orange/wiki/_pages

Two random proposals for discussion:

1) Chosing one or two examples that cover most typical use cases and put them into `serializer` module header.

2) Create a devoted `examples` module which is not imported in `package.d` but is available in documentation.

On 2013-08-13 17:09, Dicebot wrote:

> What do you think about having top-level folder with functional tests
> for a more complex packages?

I think that's a good idea.

-- 
/Jacob Carlborg

On 2013-08-13 17:12, Dicebot wrote:

> 2) Create a devoted `examples` module which is not imported in
> `package.d` but is available in documentation.

I'm wondering if the package.d module could be used for this, somehow.

-- 
/Jacob Carlborg

On 2013-08-12 15:27, Dicebot wrote:

> Jacob, it is probably worth creating a pull request with latest rebased
> version of your proposal to simplify getting a quick overview of
> changes. Also please tell if there is anything you want/need to
> implement before merging.

I have rebased now.

-- 
/Jacob Carlborg

On Tuesday, 13 August 2013 at 15:12:40 UTC, Dicebot wrote:
> On Tuesday, 13 August 2013 at 15:04:38 UTC, Jacob Carlborg wrote:
>> I worked quite hard with the documentation. There are code examples here as well, I just don't know where to put them in Phobos:
>>
>> https://github.com/jacob-carlborg/orange/wiki/_pages

I'm included to prefer the Thrift bindings over Orange since I need binary compression and type safety (XML??? yikes), inter-language operability, and most essentially, data versioning.

Nonetheless, in order to make a realistic comparison and evaulation, I need much more of the theory of operation, and a description of the Orange design.  I appreciate that you worked hard with the documentation.  But most of the essential description is missing.

Here is an outline of serialization tradeoffs and architectural issues that should be discussed in the documentation.

1. Interface Definition Language (IDL): required or not? If not, how do know the details of what to serialize. If not, how do you handle/support data versioning? If not, how do you interoperate without another language? If yes, which types are supported and what is the syntax and grammar of the IDL?

2. Is the serialized format independently de-marshallable, or is meta information required in addition?

3. Which transports if any, are integrated/supported?  Memory buffer, file descriptor, framed, zero-copy, socket, SSL support, JSON, etc.

4. Are service definitions supported (methods on objects or functions)? Are they versioned?

5. How compatible is the format with other languages?

6. How compact is the encoding?

7. How fast is to marshal and unMarshal?  What tradeoffs were made.

8. Is there a debug encoding, text that is human readable?

9. To emphasize the important point of the first item again: data versioning: how do you upgrade your cluster when a data definition changes?  If your serailization format requires simultaneous downtime for the entire cluster instead of supporting incremental upgrade, I'd say your architecture is seriously antiquated.

On Monday, August 12, 2013 21:55:00 Jacob Carlborg wrote:
> * I forgot to add that the unit tests are, a bit controversial, located in std.serialization.tests

In general, the tests should be right after the functions that they're testing and not in a separate file. I don't know that it's never appropriate to put the tests in a separate file, but none of Phobos does this right now, and I think that a very good reason is needed for doing it. I also don't know that it works very well with how the Posix makefiles compile and run each module's unit tests separately.

- Jonathan M Davis

On Tuesday, 13 August 2013 at 15:04:38 UTC, Jacob Carlborg wrote:
>
> There's a fully working example here:
>
> https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/std_serialization_serializer.html

Sorry, I think that example is WRONG!
Your example:

void main ()
{
    auto archive = new XmlArchive!();
    auto serializer = new Serializer;

    auto foo = new Foo;
    foo.a = 3;

    serializer.serialize(foo);
    auto foo2 = serializer.deserialize!(Foo)(archive.untypedData);

    writeln(foo2.a); // prints "3"
    assert(foo.a == foo2.a);
}

As I can see, it should be:

    auto archive = new XmlArchive!();
    auto serializer = new Serializer(archive);

Please fix example or correct me.

Note that current DDocs version supports to generate documentation from unittests - it lets as make shure that documentation is correct. Shall we add the condition of examples generation from unittests as required?

On Wednesday, 14 August 2013 at 02:32:20 UTC, Jonathan M Davis wrote:
> In general, the tests should be right after the functions that they're testing
> and not in a separate file. I don't know that it's never appropriate to put the
> tests in a separate file, but none of Phobos does this right now, and I think
> that a very good reason is needed for doing it. I also don't know that it
> works very well with how the Posix makefiles compile and run each module's unit
> tests separately.
>
> - Jonathan M Davis

There have been no real packages in Phobos so far. Tricky part comes when you need to test some functionality that is split across several modules - those are technically not _unit_ tests and do not belong to any specific module. I don't know what is the right approach here but I doubt existing practice can be taken blindly.

On Tuesday, 13 August 2013 at 22:54:05 UTC, glycerine wrote:
> ...

Jacob, can you add a high-level overview which answers this questions? (in any place you find convenient, until proper place for package-wide documentation is decided).

On 2013-08-14 08:29, ilya-stromberg wrote:

> Sorry, I think that example is WRONG!
> Your example:
>
> void main ()
> {
>      auto archive = new XmlArchive!();
>      auto serializer = new Serializer;
>
>      auto foo = new Foo;
>      foo.a = 3;
>
>      serializer.serialize(foo);
>      auto foo2 = serializer.deserialize!(Foo)(archive.untypedData);
>
>      writeln(foo2.a); // prints "3"
>      assert(foo.a == foo2.a);
> }
>
> As I can see, it should be:
>
>      auto archive = new XmlArchive!();
>      auto serializer = new Serializer(archive);
>
> Please fix example or correct me.

Right, good catch.

> Note that current DDocs version supports to generate documentation from
> unittests - it lets as make shure that documentation is correct. Shall
> we add the condition of examples generation from unittests as required?

How do I do that?

-- 
/Jacob Carlborg