[Development] Doc: Making it easier for devs to know if a class is supported on a given platform

[Sze Howe Koh]

Hi all,

With the proliferation of supported platforms and add-on modules, we now
have a situation where some classes are only useable on particular
platforms. There've been cases where a developer sees a class in the Qt
docs and thinks "Ooh, this is just what I need!", only to find out (after
spending time studying examples and writing code) that the class can't be
used on their platform of interest. [1]

It would be nice to help them find out earlier whether a class is available
or not.

We currently have some documentation, e.g.
http://doc.qt.io/qt-5/qtmodules.html lists "Target Platforms" for add-on
modules. However, a user who finds the class ref via a search engine might
miss this.

One idea is to add a "Target Platforms" row in the class reference, below
the "Header", "qmake", and "Inherits" rows. qdoc could populate this for
each class based on info provided about the module.

However, we have a situation in Qt Multimedia where the module is broadly
available, but particular features are not:
https://wiki.qt.io/Qt_5.5.0_Multimedia_Backends so Qt Multimedia is
available on iOS but QAudioProbe is not.

The previous idea for an auto-populated "Target Platforms" row would be
erroneous in this case. Perhaps we could have a per-class "\supports" qdoc
command, or even manually type in a line saying "This class is (not)
supported on _____"? (I'm happy to spend time doing this, but it's not a
very maintainable solution)

Any other thoughts/ideas? (I haven't thought through QML types yet)


Regards,
Sze-Howe

[1]
http://forum.qt.io/topic/63110/list-of-video-formats-qt-supports/14?page=2
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20160123/306574a9/attachment.html>