Re: [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 


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


martin



From: Development  on behalf of Sze Howe 
Koh 
Sent: Saturday, January 23, 2016 4:30 AM
To: development@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
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
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

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

[Dominik Holland]

Hi,

how about doing the automatic population, but every class is able to
override this by using the "\supports" command.

Maybe it would be also possible to add an link in the Target Platforms
row to the platform overview page of that modules (here qtmultimedia
could document what's available on which platform)

Dominik

Am 23.01.16 um 04:30 schrieb 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
> 
> 
> ___
> Development mailing list
> Development@qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development
> 
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development