[Interest] Current QDataStream format documentation?

[Thiago Macieira]

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.

I also don't think the QDataStream binary format is particularly good for non-
Qt purposes. It passes internals that are really about how Qt works, not meant 
for interchange of information. For example, QDate passes the Julian Day in 
64-bit format -- who in the world exchanges data like that? One would expect 
the serialisation format of a date and time to be something like milliseconds 
since 1970, milliseconds since 1601 or a string format, like ISO 3337. It 
passes strings as UTF-16 encoded instead of encoding with UTF-8, which would 
in turn allow interchanging QString and QByteArray serialisation formats.

It's also by default quite inefficient since it marshalls everything as big-
endian, while most CPUs are little-endian. It has no support for indexing or 
random-access seeking. It can't be used as a DOM storage, like QJsonDocument 
can.

It has no support for recovering from decoding errors, though current versions 
can actually do transactions and have limited support for it.

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

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

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

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center