[Development] QDataStream: blackbox or document all versions?

Martin Smith Martin.Smith at qt.io
Mon Sep 26 08:59:01 CEST 2016

Do we need a way to tie A specific qdoc comment to the result of a specific autotest?


From: Development <development-bounces+martin.smith=qt.io at qt-project.org> on behalf of Thiago Macieira <thiago.macieira at intel.com>
Sent: Sunday, September 25, 2016 5:58:38 AM
To: development at qt-project.org
Subject: [Development] QDataStream: blackbox or document all versions?

A thread[1] on the interest mailing list started when someone asked for the
docs for the current format of the QDataStream wire protocol, to which I
replied that it doesn't exist as we don't maintain such docs.

Long story short, we have two options:

Option 1: claim QDataStream is a blackbox and tell people that the only thing
that can read QDataStream is QDataStream. That means removing the
documentation file src/corelib/doc/src/datastreamformat.qdoc, as we don't want
people getting any ideas that they could write their own decoders or encoders.

Option 2: the opposite, saying that reading QDataStream's output is fine from
non-Qt code and it's fine to write data that QDataStream should read. This
means extending the documentation to cover ALL 17 wire formats (including
bugs) and keeping it up to date whenever someone modifies the format.

I am in favour of Option 1 because I really don't think QDataStream is a good
format for exchanging data with non-Qt code. It's designed first and foremost
for Qt's own internal data formats (sometimes even depending on internal
details), the marshalling of certain types in certain versions is buggy and
lossy. Instead, people should find a better transport format for their data, of
which we already have in Qt:

        QSettings (to an extent)

And I can add CBOR support if we want to.

[1] http://lists.qt-project.org/pipermail/interest/2016-September/024387.html
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center

Development mailing list
Development at qt-project.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20160926/ff745ab1/attachment.html>

More information about the Development mailing list