[Interest] Current QDataStream format documentation?

[Giuseppe D'Angelo]

Il 24/09/2016 02:22, Thiago Macieira ha scritto:
> On sexta-feira, 23 de setembro de 2016 19:05:28 PDT Giuseppe D'Angelo wrote:
>> Il 23/09/2016 17:14, Thiago Macieira ha scritto:
>>> The expectation is that you read QDataStream with QDataStream. You don't
>>> need to know what it writes, only that it can read what it writes.
>>
>> Where has this expectation *ever* been stated? The very fact that we
>> document the wire format is so that people can use something different
>> than QDataStream to read the output (or provide input into it).
> 
> Nowhere. That's my expectation. Which is why as a maintainer I don't maintain 
> the documentation format, as I don't see the value.

What's the opinion of the documentation maintainer on this particular issue?

> I also don't think the QDataStream binary format is particularly good for non-

[snip]

While I agree, I'm not going into detail about the quality of
QDataStream, as that's not what this topic is for...

> 
>> I keep my point that we have problems in the process, because:
>>
>> 1) at release time (?) we bump QDataStream's output version enum without
>> updating that documentation page about the wire format. (I don't even
>> understand how the decision about bumping the version number or not
>> bumping it is done. A flag in [ChangeLog]? Manual grepping? Emails on
>> the list?)
> 
> The decision is like this: it starts equal to the last release's number. If 
> you modify one of the operator<<, you bump the number.

But "you" who? The release manager at release time? Whoever submits a
change that changes operator<<? (And then the release manager needs to
check if the version has already been bumped, otherwise just declare a
new version equal to the old one?)

> 
>> 2) we have types which change serialization format depending on the
>> stream's version, and we don't document what's exactly serialized for
>> each version. What do I get if, when using 5.8, I stream a QDateTime
>> using the Qt_3_3 format?
> 
> You get Qt_3_3's format, which hopefully Qt 3.3 code could still read.

(And Qt 5.8 code too if I set the 3_3 format), but my question was about
"what do I get on the wire". Again, I think it should be on that page
(so one doesn't need to go search on the wayback machine).

> 
>> 2b) we must enforce as a review rule that the wire format documentation
>> page must be updated together with every patch that changes how a type
>> is serialized.
> 
> I disagree and my reasons are stated previously in this thread. I'd even 
> remove the page that details the format.
> 
>> If you think the above is wrong, then please do submit a change that
>> gets rid of the wire format page and adds a note in QDataStream's
>> documentation to tell people that QDataStream only interacts with
>> QDataStream.
> 
> I can do that. Though I guess this should be a discussion on the dev mailing 
> list first.

Sure, let's start that one.

Cheers,
-- 
Giuseppe D'Angelo | giuseppe.dangelo at kdab.com | Senior Software Engineer
KDAB (UK) Ltd., a KDAB Group company | Tel: UK +44-1625-809908
KDAB - Qt, C++ and OpenGL Experts

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4007 bytes
Desc: Firma crittografica S/MIME
URL: <http://lists.qt-project.org/pipermail/interest/attachments/20160924/bffe5715/attachment.bin>