doc: Add brief and group for native type conversions

Change-Id: I74608619201bf77e487fb986bf213b349cc22f6a
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

3 files changed, 175 insertions, 101 deletions

diff --git a/src/corelib/kernel/qcore_foundation.mm b/src/corelib/kernel/qcore_foundation.mm
index eb3c70756a..5520b1fb24 100644
--- a/src/corelib/kernel/qcore_foundation.mm
+++ b/src/corelib/kernel/qcore_foundation.mm
@@ -62,9 +62,10 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-    \since 5.3
+    \brief Constructs a new QByteArray containing a copy of the CFData \a data.
 
-    Constructs a new QByteArray containing a copy of the CFData \a data.
+    \since 5.3
+    \ingroup platform-type-conversions
 
     \sa fromRawCFData(), fromRawData(), toRawCFData(), toCFData()
 */
@@ -77,15 +78,16 @@ QByteArray QByteArray::fromCFData(CFDataRef data)
 }
 
 /*!
-    \since 5.3
-
-    Constructs a QByteArray that uses the bytes of the CFData \a data.
+    \brief Constructs a QByteArray that uses the bytes of the CFData \a data.
 
     The \a data's bytes are not copied.
 
     The caller guarantees that the CFData will not be deleted
     or modified as long as this QByteArray object exists.
 
+    \since 5.3
+    \ingroup platform-type-conversions
+
     \sa fromCFData(), fromRawData(), toRawCFData(), toCFData()
 */
 QByteArray QByteArray::fromRawCFData(CFDataRef data)
@@ -97,10 +99,12 @@ QByteArray QByteArray::fromRawCFData(CFDataRef data)
 }
 
 /*!
-    \since 5.3
+    \brief Creates a CFData from a QByteArray.
 
-    Creates a CFData from a QByteArray. The caller owns the CFData object
-    and is responsible for releasing it.
+    The caller owns the CFData object and is responsible for releasing it.
+
+    \since 5.3
+    \ingroup platform-type-conversions
 
     \sa toRawCFData(), fromCFData(), fromRawCFData(), fromRawData()
 */
@@ -110,15 +114,16 @@ CFDataRef QByteArray::toCFData() const
 }
 
 /*!
-    \since 5.3
-
-    Constructs a CFData that uses the bytes of the QByteArray.
+    \brief Constructs a CFData that uses the bytes of the QByteArray.
 
     The QByteArray's bytes are not copied.
 
     The caller guarantees that the QByteArray will not be deleted
     or modified as long as this CFData object exists.
 
+    \since 5.3
+    \ingroup platform-type-conversions
+
     \sa toCFData(), fromRawCFData(), fromCFData(), fromRawData()
 */
 CFDataRef QByteArray::toRawCFData() const
@@ -128,9 +133,10 @@ CFDataRef QByteArray::toRawCFData() const
 }
 
 /*!
-    \since 5.3
+    \brief Constructs a new QByteArray containing a copy of the NSData \a data.
 
-    Constructs a new QByteArray containing a copy of the NSData \a data.
+    \since 5.3
+    \ingroup platform-type-conversions
 
     \sa fromRawNSData(), fromRawData(), toNSData(), toRawNSData()
 */
@@ -142,15 +148,16 @@ QByteArray QByteArray::fromNSData(const NSData *data)
 }
 
 /*!
-    \since 5.3
-
-    Constructs a QByteArray that uses the bytes of the NSData \a data.
+    \brief Constructs a QByteArray that uses the bytes of the NSData \a data.
 
     The \a data's bytes are not copied.
 
     The caller guarantees that the NSData will not be deleted
     or modified as long as this QByteArray object exists.
 
+    \since 5.3
+    \ingroup platform-type-conversions
+
     \sa fromNSData(), fromRawData(), toRawNSData(), toNSData()
 */
 QByteArray QByteArray::fromRawNSData(const NSData *data)
@@ -161,9 +168,12 @@ QByteArray QByteArray::fromRawNSData(const NSData *data)
 }
 
 /*!
-    \since 5.3
+    \brief Creates a NSData from a QByteArray.
 
-    Creates a NSData from a QByteArray. The NSData object is autoreleased.
+    The NSData object is autoreleased.
+
+    \since 5.3
+    \ingroup platform-type-conversions
 
     \sa fromNSData(), fromRawNSData(), fromRawData(), toRawNSData()
 */
@@ -173,15 +183,16 @@ NSData *QByteArray::toNSData() const
 }
 
 /*!
-    \since 5.3
-
-    Constructs a NSData that uses the bytes of the QByteArray.
+    \brief Constructs a NSData that uses the bytes of the QByteArray.
 
     The QByteArray's bytes are not copied.
 
     The caller guarantees that the QByteArray will not be deleted
     or modified as long as this NSData object exists.
 
+    \since 5.3
+    \ingroup platform-type-conversions
+
     \sa fromRawNSData(), fromNSData(), fromRawData(), toNSData()
 */
 NSData *QByteArray::toRawNSData() const
@@ -193,11 +204,12 @@ NSData *QByteArray::toRawNSData() const
 // ----------------------------------------------------------------------------
 
 /*!
-    \since 5.2
-
-    Constructs a new QString containing a copy of the \a string CFString.
+    \brief Constructs a new QString containing a copy of the \a string CFString.
 
     \note this function is only available on \macos and iOS.
+
+    \since 5.2
+    \ingroup platform-type-conversions
 */
 QString QString::fromCFString(CFStringRef string)
 {
@@ -217,12 +229,14 @@ QString QString::fromCFString(CFStringRef string)
 }
 
 /*!
-    \since 5.2
+    \brief Creates a CFString from a QString.
 
-    Creates a CFString from a QString. The caller owns the CFString and is
-    responsible for releasing it.
+    The caller owns the CFString and is responsible for releasing it.
 
     \note this function is only available on \macos and iOS.
+
+    \since 5.2
+    \ingroup platform-type-conversions
 */
 CFStringRef QString::toCFString() const
 {
@@ -230,12 +244,14 @@ CFStringRef QString::toCFString() const
 }
 
 /*!
-    \since 6.0
+    \brief Creates a CFString from this QStringView.
 
-    Creates a CFString from this QStringView. The caller owns the CFString and is
-    responsible for releasing it.
+    The caller owns the CFString and is responsible for releasing it.
 
     \note this function is only available on \macos and iOS.
+
+    \since 6.0
+    \ingroup platform-type-conversions
 */
 CFStringRef QStringView::toCFString() const
 {
@@ -243,11 +259,12 @@ CFStringRef QStringView::toCFString() const
 }
 
 /*!
-    \since 5.2
-
-    Constructs a new QString containing a copy of the \a string NSString.
+    \brief Constructs a new QString containing a copy of the \a string NSString.
 
     \note this function is only available on \macos and iOS.
+
+    \since 5.2
+    \ingroup platform-type-conversions
 */
 QString QString::fromNSString(const NSString *string)
 {
@@ -260,11 +277,14 @@ QString QString::fromNSString(const NSString *string)
 }
 
 /*!
-    \since 5.2
+    \brief Creates a NSString from a QString.
 
-    Creates a NSString from a QString. The NSString is autoreleased.
+    The NSString is autoreleased.
 
     \note this function is only available on \macos and iOS.
+
+    \since 5.2
+    \ingroup platform-type-conversions
 */
 NSString *QString::toNSString() const
 {
@@ -272,11 +292,14 @@ NSString *QString::toNSString() const
 }
 
 /*!
-    \since 6.0
+    \brief Creates an NSString from this QStringView.
 
-    Creates an NSString from this QStringView. The NSString is autoreleased.
+    The NSString is autoreleased.
 
     \note this function is only available on \macos and iOS.
+
+    \since 6.0
+    \ingroup platform-type-conversions
 */
 NSString *QStringView::toNSString() const
 {
@@ -286,11 +309,12 @@ NSString *QStringView::toNSString() const
 // ----------------------------------------------------------------------------
 
 /*!
-    \since 5.7
-
-    Constructs a new QUuid containing a copy of the \a uuid CFUUID.
+    \brief Constructs a new QUuid containing a copy of the \a uuid CFUUID.
 
     \note this function is only available on Apple platforms.
+
+    \since 5.7
+    \ingroup platform-type-conversions
 */
 QUuid QUuid::fromCFUUID(CFUUIDRef uuid)
 {
@@ -301,12 +325,14 @@ QUuid QUuid::fromCFUUID(CFUUIDRef uuid)
 }
 
 /*!
-    \since 5.7
+    \brief Creates a CFUUID from a QUuid.
 
-    Creates a CFUUID from a QUuid. The caller owns the CFUUID and is
-    responsible for releasing it.
+    The caller owns the CFUUID and is responsible for releasing it.
 
     \note this function is only available on Apple platforms.
+
+    \since 5.7
+    \ingroup platform-type-conversions
 */
 CFUUIDRef QUuid::toCFUUID() const
 {
@@ -315,11 +341,12 @@ CFUUIDRef QUuid::toCFUUID() const
 }
 
 /*!
-    \since 5.7
-
-    Constructs a new QUuid containing a copy of the \a uuid NSUUID.
+    \brief Constructs a new QUuid containing a copy of the \a uuid NSUUID.
 
     \note this function is only available on Apple platforms.
+
+    \since 5.7
+    \ingroup platform-type-conversions
 */
 QUuid QUuid::fromNSUUID(const NSUUID *uuid)
 {
@@ -331,11 +358,14 @@ QUuid QUuid::fromNSUUID(const NSUUID *uuid)
 }
 
 /*!
-    \since 5.7
+    \brief Creates a NSUUID from a QUuid.
 
-    Creates a NSUUID from a QUuid. The NSUUID is autoreleased.
+    The NSUUID is autoreleased.
 
     \note this function is only available on Apple platforms.
+
+    \since 5.7
+    \ingroup platform-type-conversions
 */
 NSUUID *QUuid::toNSUUID() const
 {
@@ -347,9 +377,10 @@ NSUUID *QUuid::toNSUUID() const
 
 
 /*!
-    \since 5.2
+    \brief Constructs a QUrl containing a copy of the CFURL \a url.
 
-    Constructs a QUrl containing a copy of the CFURL \a url.
+    \since 5.2
+    \ingroup platform-type-conversions
 */
 QUrl QUrl::fromCFURL(CFURLRef url)
 {
@@ -359,10 +390,12 @@ QUrl QUrl::fromCFURL(CFURLRef url)
 }
 
 /*!
-    \since 5.2
+    \brief Creates a CFURL from a QUrl.
 
-    Creates a CFURL from a QUrl. The caller owns the CFURL and is
-    responsible for releasing it.
+    The caller owns the CFURL and is responsible for releasing it.
+
+    \since 5.2
+    \ingroup platform-type-conversions
 */
 CFURLRef QUrl::toCFURL() const
 {
@@ -376,9 +409,10 @@ CFURLRef QUrl::toCFURL() const
 }
 
 /*!
-    \since 5.2
+    \brief Constructs a QUrl containing a copy of the NSURL \a url.
 
-    Constructs a QUrl containing a copy of the NSURL \a url.
+    \since 5.2
+    \ingroup platform-type-conversions
 */
 QUrl QUrl::fromNSURL(const NSURL *url)
 {
@@ -388,9 +422,12 @@ QUrl QUrl::fromNSURL(const NSURL *url)
 }
 
 /*!
-    \since 5.2
+    \brief Creates a NSURL from a QUrl.
 
-    Creates a NSURL from a QUrl. The NSURL is autoreleased.
+    The NSURL is autoreleased.
+
+    \since 5.2
+    \ingroup platform-type-conversions
 */
 NSURL *QUrl::toNSURL() const
 {
@@ -401,9 +438,10 @@ NSURL *QUrl::toNSURL() const
 
 
 /*!
-    \since 5.5
+    \brief Constructs a new QDateTime containing a copy of the CFDate \a date.
 
-    Constructs a new QDateTime containing a copy of the CFDate \a date.
+    \since 5.5
+    \ingroup platform-type-conversions
 
     \sa toCFDate()
 */
@@ -416,10 +454,12 @@ QDateTime QDateTime::fromCFDate(CFDateRef date)
 }
 
 /*!
-    \since 5.5
+    \brief Creates a CFDate from a QDateTime.
+
+    The caller owns the CFDate object and is responsible for releasing it.
 
-    Creates a CFDate from a QDateTime. The caller owns the CFDate object
-    and is responsible for releasing it.
+    \since 5.5
+    \ingroup platform-type-conversions
 
     \sa fromCFDate()
 */
@@ -430,9 +470,10 @@ CFDateRef QDateTime::toCFDate() const
 }
 
 /*!
-    \since 5.5
+    \brief Constructs a new QDateTime containing a copy of the NSDate \a date.
 
-    Constructs a new QDateTime containing a copy of the NSDate \a date.
+    \since 5.5
+    \ingroup platform-type-conversions
 
     \sa toNSDate()
 */
@@ -444,9 +485,12 @@ QDateTime QDateTime::fromNSDate(const NSDate *date)
 }
 
 /*!
-    \since 5.5
+    \brief Creates an NSDate from a QDateTime.
 
-    Creates an NSDate from a QDateTime. The NSDate object is autoreleased.
+    The NSDate object is autoreleased.
+
+    \since 5.5
+    \ingroup platform-type-conversions
 
     \sa fromNSDate()
 */
@@ -460,9 +504,10 @@ NSDate *QDateTime::toNSDate() const
 
 #if QT_CONFIG(timezone) && !defined(QT_NO_SYSTEMLOCALE)
 /*!
-    \since 5.9
+    \brief Constructs a new QTimeZone containing a copy of the CFTimeZone \a timeZone.
 
-    Constructs a new QTimeZone containing a copy of the CFTimeZone \a timeZone.
+    \since 5.9
+    \ingroup platform-type-conversions
 
     \sa toCFTimeZone()
 */
@@ -474,10 +519,12 @@ QTimeZone QTimeZone::fromCFTimeZone(CFTimeZoneRef timeZone)
 }
 
 /*!
-    \since 5.9
+    \brief Creates a CFTimeZone from a QTimeZone.
 
-    Creates a CFTimeZone from a QTimeZone. The caller owns the CFTimeZone object
-    and is responsible for releasing it.
+    The caller owns the CFTimeZone object and is responsible for releasing it.
+
+    \since 5.9
+    \ingroup platform-type-conversions
 
     \sa fromCFTimeZone()
 */
@@ -491,9 +538,10 @@ CFTimeZoneRef QTimeZone::toCFTimeZone() const
 }
 
 /*!
-    \since 5.9
+    \brief Constructs a new QTimeZone containing a copy of the NSTimeZone \a timeZone.
 
-    Constructs a new QTimeZone containing a copy of the NSTimeZone \a timeZone.
+    \since 5.9
+    \ingroup platform-type-conversions
 
     \sa toNSTimeZone()
 */
@@ -505,9 +553,12 @@ QTimeZone QTimeZone::fromNSTimeZone(const NSTimeZone *timeZone)
 }
 
 /*!
-    \since 5.9
+    \brief Creates an NSTimeZone from a QTimeZone.
 
-    Creates an NSTimeZone from a QTimeZone. The NSTimeZone object is autoreleased.
+    The NSTimeZone object is autoreleased.
+
+    \since 5.9
+    \ingroup platform-type-conversions
 
     \sa fromNSTimeZone()
 */
@@ -520,9 +571,10 @@ NSTimeZone *QTimeZone::toNSTimeZone() const
 // ----------------------------------------------------------------------------
 
 /*!
-    \since 5.8
+    \brief Creates a CGRect from a QRect.
 
-    Creates a CGRect from a QRect.
+    \since 5.8
+    \ingroup platform-type-conversions
 
     \sa QRectF::fromCGRect()
 */
@@ -532,9 +584,10 @@ CGRect QRect::toCGRect() const noexcept
 }
 
 /*!
-    \since 5.8
+    \brief Creates a CGRect from a QRectF.
 
-    Creates a CGRect from a QRectF.
+    \since 5.8
+    \ingroup platform-type-conversions
 
     \sa fromCGRect()
 */
@@ -544,9 +597,10 @@ CGRect QRectF::toCGRect() const noexcept
 }
 
 /*!
-    \since 5.8
+    \brief Creates a QRectF from CGRect \a rect.
 
-    Creates a QRectF from CGRect \a rect.
+    \since 5.8
+    \ingroup platform-type-conversions
 
     \sa toCGRect()
 */
@@ -558,9 +612,10 @@ QRectF QRectF::fromCGRect(CGRect rect) noexcept
 // ----------------------------------------------------------------------------
 
 /*!
-    \since 5.8
+    \brief Creates a CGPoint from a QPoint.
 
-    Creates a CGPoint from a QPoint.
+    \since 5.8
+    \ingroup platform-type-conversions
 
     \sa QPointF::fromCGPoint()
 */
@@ -570,9 +625,10 @@ CGPoint QPoint::toCGPoint() const noexcept
 }
 
 /*!
-    \since 5.8
+    \brief Creates a CGPoint from a QPointF.
 
-    Creates a CGPoint from a QPointF.
+    \since 5.8
+    \ingroup platform-type-conversions
 
     \sa fromCGPoint()
 */
@@ -582,9 +638,10 @@ CGPoint QPointF::toCGPoint() const noexcept
 }
 
 /*!
-    \since 5.8
+    \brief Creates a QRectF from CGPoint \a point.
 
-    Creates a QRectF from CGPoint \a point.
+    \since 5.8
+    \ingroup platform-type-conversions
 
     \sa toCGPoint()
 */
@@ -596,9 +653,10 @@ QPointF QPointF::fromCGPoint(CGPoint point) noexcept
 // ----------------------------------------------------------------------------
 
 /*!
-    \since 5.8
+    \brief Creates a CGSize from a QSize.
 
-    Creates a CGSize from a QSize.
+    \since 5.8
+    \ingroup platform-type-conversions
 
     \sa QSizeF::fromCGSize()
 */
@@ -608,9 +666,10 @@ CGSize QSize::toCGSize() const noexcept
 }
 
 /*!
-    \since 5.8
+    \brief Creates a CGSize from a QSizeF.
 
-    Creates a CGSize from a QSizeF.
+    \since 5.8
+    \ingroup platform-type-conversions
 
     \sa fromCGSize()
 */
@@ -620,9 +679,10 @@ CGSize QSizeF::toCGSize() const noexcept
 }
 
 /*!
-    \since 5.8
+    \brief Creates a QRectF from \a size.
 
-    Creates a QRectF from \a size.
+    \since 5.8
+    \ingroup platform-type-conversions
 
     \sa toCGSize()
 */
diff --git a/src/gui/image/qimage_darwin.mm b/src/gui/image/qimage_darwin.mm
index 7ca1a0869a..83b6cef980 100644
--- a/src/gui/image/qimage_darwin.mm
+++ b/src/gui/image/qimage_darwin.mm
@@ -48,8 +48,9 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-    Creates a \c CGImage equivalent to this QImage. Returns a
-    \c CGImageRef handle.
+    \brief Creates a \c CGImage equivalent to this QImage.
+
+    Returns a \c CGImageRef handle.
 
     The returned CGImageRef partakes in the QImage implicit sharing,
     and holds a reference to the QImage data. CGImage is immutable
@@ -92,6 +93,8 @@ QT_BEGIN_NAMESPACE
 
     The CGImageRef color space is set to the sRGB color space.
 
+    \ingroup platform-type-conversions
+
     \sa QtMac::toNSImage()
 */
 CGImageRef QImage::toCGImage() const
diff --git a/src/gui/image/qpixmap_win.cpp b/src/gui/image/qpixmap_win.cpp
index cd7a8ca80e..aae4a1cbf4 100644
--- a/src/gui/image/qpixmap_win.cpp
+++ b/src/gui/image/qpixmap_win.cpp
@@ -352,8 +352,9 @@ Q_GUI_EXPORT HBITMAP qt_imageToWinHBITMAP(const QImage &imageIn, int hbitmapForm
 /*!
     \since 6.0
 
-    Creates a \c HBITMAP equivalent of the QImage. Returns the \c HBITMAP
-    handle.
+    \brief Creates a \c HBITMAP equivalent of the QImage.
+
+    Returns the \c HBITMAP handle.
 
     It is the caller's responsibility to free the \c HBITMAP data
     after use.
@@ -368,6 +369,8 @@ Q_GUI_EXPORT HBITMAP qt_imageToWinHBITMAP(const QImage &imageIn, int hbitmapForm
     When using the resulting HBITMAP as application icon or a systray icon,
     the image should have the format QImage::Format_ARGB32.
 
+    \ingroup platform-type-conversions
+
     \sa fromHBITMAP(), convertToFormat()
 */
 HBITMAP QImage::toHBITMAP() const
@@ -493,7 +496,7 @@ Q_GUI_EXPORT QImage qt_imageFromWinHBITMAP(HBITMAP bitmap, int hbitmapFormat = 0
 /*!
     \since 6.0
 
-    Returns a QImage that is equivalent to the given \a hbitmap.
+    \brief Returns a QImage that is equivalent to the given \a hbitmap.
 
     HBITMAP does not store information about the alpha channel.
 
@@ -505,6 +508,8 @@ Q_GUI_EXPORT QImage qt_imageFromWinHBITMAP(HBITMAP bitmap, int hbitmapFormat = 0
     \c reinterpretAsFormat(QImage::Format_ARGB32) should be called
     on the returned image to ensure the format is correct.
 
+    \ingroup platform-type-conversions
+
     \sa toHBITMAP(), reinterpretAsFormat()
 */
 QImage QImage::fromHBITMAP(HBITMAP hbitmap)
@@ -520,12 +525,16 @@ Q_GUI_EXPORT QPixmap qt_pixmapFromWinHBITMAP(HBITMAP bitmap, int hbitmapFormat =
 /*!
     \since 6.0
 
-    Creates a \c HICON equivalent of the QPixmap, applying the mask
-    \a mask. If \a mask is not null, it needs to be of format QImage::Format_Mono.
+    \brief Creates a \c HICON equivalent of the QPixmap, applying the mask
+    \a mask.
+
+    If \a mask is not null, it needs to be of format QImage::Format_Mono.
     Returns the \c HICON handle.
 
     It is the caller's responsibility to free the \c HICON data after use.
 
+    \ingroup platform-type-conversions
+
     \sa fromHICON()
 */
 HICON QImage::toHICON(const QImage &mask) const
@@ -609,7 +618,9 @@ static inline bool hasAlpha(const QImage &image)
 /*!
     \since 6.0
 
-    Returns a QImage that is equivalent to the given \a icon.
+    \brief Returns a QImage that is equivalent to the given \a icon.
+
+    \ingroup platform-type-conversions
 
     \sa toHICON()
 */