[Development] QDataStream: blackbox or document all versions?

[Jędrzej Nowacki]

On lørdag 24. september 2016 20.58.38 CEST Thiago Macieira wrote:
> 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:
> 
> 	XML
> 	JSON
> 	D-Bus
> 	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

Hi,

 Option 4: Document only basic types, like char, int, maybe QByteArray and 
QString, QVector. Everything above is tight to Qt implementation and therefore 
is super hard to use from 3rd party perspective as it is changing often.

  But I agree with you QDataStream is not a good format for exchanging data 
with non-Qt code so option 1 is Ok too.

Cheers,
  Jędrek