On 2013-08-14 09:19, Dicebot 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).

Yes, I could do that.

-- 
/Jacob Carlborg

On Wednesday, 14 August 2013 at 07:29:48 UTC, Jacob Carlborg wrote:
>> 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?

http://dlang.org/changelog.html#documentedunittest

On 2013-08-14 00:54, glycerine wrote:

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

It seems like we have a different meaning of "essential". I have documented the package for what it is, not for what it's not. It's a package for serialization, not a RCP or network package. SSL support doesn't make sense, it's like asking "Does std.algorithm.map has SSL support?".

You seem to like me to write a comparison to Thrift in the documentation. You have to make the comparison yourself.

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

Many of these questions doesn't even make sense, as I stated above.

-- 
/Jacob Carlborg

On 2013-08-14 09:32, Dicebot wrote:

> http://dlang.org/changelog.html#documentedunittest

Thanks.

-- 
/Jacob Carlborg

On 2013-08-14 09:19, Dicebot 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).

Actually, I'm not so sure about that. He wants me to do a comparison to Thrift.

-- 
/Jacob Carlborg

On Wednesday, 14 August 2013 at 07:43:22 UTC, Jacob Carlborg wrote:
> On 2013-08-14 09:19, Dicebot 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).
>
> Actually, I'm not so sure about that. He wants me to do a comparison to Thrift.

I did not mean to answer these questions specifically - just provide a high-level overview of what std.serialization is. Architecture, use case domain etc. - to avoid similar confusion from people exploring standard library documentation. If such misunderstanding has happened once, it is likely to happen again.

On 2013-08-14 09:46, Dicebot wrote:

> I did not mean to answer these questions specifically - just provide a
> high-level overview of what std.serialization is. Architecture, use case
> domain etc. - to avoid similar confusion from people exploring standard
> library documentation. If such misunderstanding has happened once, it is
> likely to happen again.

Ok, ok, I'll do that.

-- 
/Jacob Carlborg

Serious:

- doesn't use ranges
  - does this store the entire serialized output in memory?
  - I would to serialize to a range (file?) and deserialize from a range (file?)

Minor

- Indentation messed up in Serializable example
- Typo: NonSerialized example should read NonSerialized!(b)

On 2013-08-14 10:19, Tyler Jameson Little wrote:
> Serious:
>
> - doesn't use ranges
>    - does this store the entire serialized output in memory?

That's up to the archive how it chooses to implement it. But the current XmlArchive does so, yes. I becomes quite limited because of std.xml.

>    - I would to serialize to a range (file?) and deserialize from a
> range (file?)

The serialized data is returned as an array, so that is compatible with the range interface, it just won't be lazy.

The input data used for deserializing excepts a void[], I don't think that's compatible with the range interface.

> Minor
>
> - Indentation messed up in Serializable example

Right, I'll fix that.

> - Typo: NonSerialized example should read NonSerialized!(b)

No, it's not a typo. If you read the documentation you'll see that:

"If no fields or "this" is specified, it indicates that the whole class/struct should not be (de)serialized."

-- 
/Jacob Carlborg

On Wednesday, 14 August 2013 at 08:48:23 UTC, Jacob Carlborg wrote:
> On 2013-08-14 10:19, Tyler Jameson Little wrote:
>> Serious:
>>
>> - doesn't use ranges
>>   - does this store the entire serialized output in memory?
>
> That's up to the archive how it chooses to implement it. But the current XmlArchive does so, yes. I becomes quite limited because of std.xml.

Well, std.xml needs to be replaced anyway, so it's probably not a good limitation to have. It may take some work to replace it correctly though...

>>   - I would to serialize to a range (file?) and deserialize from a
>> range (file?)
>
> The serialized data is returned as an array, so that is compatible with the range interface, it just won't be lazy.
>
> The input data used for deserializing excepts a void[], I don't think that's compatible with the range interface.

I'm mostly interested in reducing memory. If I'm (de)serializing a large object or lots of objects, this could become an issue.

Related question: Have you looked at how much this relies on the GC?

>> Minor
>>
>> - Indentation messed up in Serializable example
>
> Right, I'll fix that.
>
>> - Typo: NonSerialized example should read NonSerialized!(b)
>
> No, it's not a typo. If you read the documentation you'll see that:
>
> "If no fields or "this" is specified, it indicates that the whole class/struct should not be (de)serialized."

Ah, missed that.