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

[Smith Martin]

I suppose the default should be that a class is fully supported on all Qt platforms, so the qdoc command should be \notsupported with the list of not supported platforms.


\notsupported <platform list>


...could appear in a \class or a \fn or in a \qmltype or \qmlmethod.


martin


________________________________
From: Development <development-bounces at qt-project.org> on behalf of Sze Howe Koh <szehowe.koh at gmail.com>
Sent: Saturday, January 23, 2016 4:30 AM
To: development at qt-project.org
Subject: [Development] Doc: Making it easier for devs to know if a class is supported on a given platform

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.
All Modules | Qt 5.5<http://doc.qt.io/qt-5/qtmodules.html>
doc.qt.io
If you use qmake to build your projects, the Qt Core and Qt GUI modules are included by default. To link only against Qt Core, add the following line to your .pro file:



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/20160125/dc5a944c/attachment.html>