darwin: Move conversion function documentation to function definition

It's easier to maintain the function and the docs when they live together.

Change-Id: I1e047b4ac1eb61a36849188da560dd899e05509f
Reviewed-by: Jake Petroules <jake.petroules@qt.io>

10 files changed, 188 insertions, 212 deletions

diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp
index 1e409c105c..3c1d314d20 100644
--- a/src/corelib/io/qurl.cpp
+++ b/src/corelib/io/qurl.cpp
@@ -3452,33 +3452,6 @@ QByteArray QUrl::toPercentEncoding(const QString &input, const QByteArray &exclu
     return input.toUtf8().toPercentEncoding(exclude, include);
 }
 
-/*! \fn QUrl QUrl::fromCFURL(CFURLRef url)
-    \since 5.2
-
-    Constructs a QUrl containing a copy of the CFURL \a url.
-*/
-
-/*! \fn CFURLRef QUrl::toCFURL() const
-    \since 5.2
-
-    Creates a CFURL from a QUrl. The caller owns the CFURL and is
-    responsible for releasing it.
-*/
-
-/*!
-    \fn QUrl QUrl::fromNSURL(const NSURL *url)
-    \since 5.2
-
-    Constructs a QUrl containing a copy of the NSURL \a url.
-*/
-
-/*!
-    \fn NSURL* QUrl::toNSURL() const
-    \since 5.2
-
-    Creates a NSURL from a QUrl. The NSURL is autoreleased.
-*/
-
 /*!
     \internal
     \since 5.0
diff --git a/src/corelib/io/qurl_mac.mm b/src/corelib/io/qurl_mac.mm
index 04d05f1b23..89c1b50b31 100644
--- a/src/corelib/io/qurl_mac.mm
+++ b/src/corelib/io/qurl_mac.mm
@@ -45,11 +45,22 @@
 
 QT_BEGIN_NAMESPACE
 
+/*! \fn QUrl QUrl::fromCFURL(CFURLRef url)
+    \since 5.2
+
+    Constructs a QUrl containing a copy of the CFURL \a url.
+*/
 QUrl QUrl::fromCFURL(CFURLRef url)
 {
     return QUrl(QString::fromCFString(CFURLGetString(url)));
 }
 
+/*! \fn CFURLRef QUrl::toCFURL() const
+    \since 5.2
+
+    Creates a CFURL from a QUrl. The caller owns the CFURL and is
+    responsible for releasing it.
+*/
 CFURLRef QUrl::toCFURL() const
 {
     CFURLRef url = 0;
@@ -61,11 +72,23 @@ CFURLRef QUrl::toCFURL() const
     return url;
 }
 
+/*!
+    \fn QUrl QUrl::fromNSURL(const NSURL *url)
+    \since 5.2
+
+    Constructs a QUrl containing a copy of the NSURL \a url.
+*/
 QUrl QUrl::fromNSURL(const NSURL *url)
 {
     return QUrl(QString::fromNSString([url absoluteString]));
 }
 
+/*!
+    \fn NSURL* QUrl::toNSURL() const
+    \since 5.2
+
+    Creates a NSURL from a QUrl. The NSURL is autoreleased.
+*/
 NSURL *QUrl::toNSURL() const
 {
     return [NSURL URLWithString:toString(FullyEncoded).toNSString()];
diff --git a/src/corelib/plugin/quuid.cpp b/src/corelib/plugin/quuid.cpp
index 5876bb84c3..1780039928 100644
--- a/src/corelib/plugin/quuid.cpp
+++ b/src/corelib/plugin/quuid.cpp
@@ -809,39 +809,6 @@ QUuid::Version QUuid::version() const Q_DECL_NOTHROW
     return ver;
 }
 
-/*! \fn QUuid QUuid::fromCFUUID(CFUUIDRef uuid)
-    \since 5.7
-
-    Constructs a new QUuid containing a copy of the \a uuid CFUUID.
-
-    \note this function is only available on Apple platforms.
-*/
-
-/*! \fn CFUUIDRef QUuid::toCFUUID() const
-    \since 5.7
-
-    Creates a CFUUID from a QUuid. The caller owns the CFUUID and is
-    responsible for releasing it.
-
-    \note this function is only available on Apple platforms.
-*/
-
-/*! \fn QUuid QUuid::fromNSUUID(const NSUUID *uuid)
-    \since 5.7
-
-    Constructs a new QUuid containing a copy of the \a uuid NSUUID.
-
-    \note this function is only available on Apple platforms.
-*/
-
-/*! \fn NSUUID QUuid::toNSUUID() const
-    \since 5.7
-
-    Creates a NSUUID from a QUuid. The NSUUID is autoreleased.
-
-    \note this function is only available on Apple platforms.
-*/
-
 /*!
     \fn bool QUuid::operator<(const QUuid &other) const
 
diff --git a/src/corelib/plugin/quuid_darwin.mm b/src/corelib/plugin/quuid_darwin.mm
index c2a7240f3b..aa67e0b7dc 100644
--- a/src/corelib/plugin/quuid_darwin.mm
+++ b/src/corelib/plugin/quuid_darwin.mm
@@ -43,6 +43,13 @@
 
 QT_BEGIN_NAMESPACE
 
+/*! \fn QUuid QUuid::fromCFUUID(CFUUIDRef uuid)
+    \since 5.7
+
+    Constructs a new QUuid containing a copy of the \a uuid CFUUID.
+
+    \note this function is only available on Apple platforms.
+*/
 QUuid QUuid::fromCFUUID(CFUUIDRef uuid)
 {
     if (!uuid)
@@ -51,12 +58,27 @@ QUuid QUuid::fromCFUUID(CFUUIDRef uuid)
     return QUuid::fromRfc4122(QByteArray::fromRawData(reinterpret_cast<const char *>(&bytes), sizeof(bytes)));
 }
 
+/*! \fn CFUUIDRef QUuid::toCFUUID() const
+    \since 5.7
+
+    Creates a CFUUID from a QUuid. The caller owns the CFUUID and is
+    responsible for releasing it.
+
+    \note this function is only available on Apple platforms.
+*/
 CFUUIDRef QUuid::toCFUUID() const
 {
     const QByteArray bytes = toRfc4122();
     return CFUUIDCreateFromUUIDBytes(0, *reinterpret_cast<const CFUUIDBytes *>(bytes.constData()));
 }
 
+/*! \fn QUuid QUuid::fromNSUUID(const NSUUID *uuid)
+    \since 5.7
+
+    Constructs a new QUuid containing a copy of the \a uuid NSUUID.
+
+    \note this function is only available on Apple platforms.
+*/
 QUuid QUuid::fromNSUUID(const NSUUID *uuid)
 {
     if (!uuid)
@@ -66,6 +88,13 @@ QUuid QUuid::fromNSUUID(const NSUUID *uuid)
     return QUuid::fromRfc4122(QByteArray::fromRawData(reinterpret_cast<const char *>(bytes), sizeof(bytes)));
 }
 
+/*! \fn NSUUID QUuid::toNSUUID() const
+    \since 5.7
+
+    Creates a NSUUID from a QUuid. The NSUUID is autoreleased.
+
+    \note this function is only available on Apple platforms.
+*/
 NSUUID *QUuid::toNSUUID() const
 {
     const QByteArray bytes = toRfc4122();
diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp
index 2efe3c1a86..a256b44b1f 100644
--- a/src/corelib/tools/qbytearray.cpp
+++ b/src/corelib/tools/qbytearray.cpp
@@ -4375,91 +4375,6 @@ QByteArray QByteArray::fromPercentEncoding(const QByteArray &input, char percent
     \sa fromStdString(), QString::toStdString()
 */
 
-/*! \fn QByteArray QByteArray::fromCFData(CFDataRef data)
-    \since 5.3
-
-    Constructs a new QByteArray containing a copy of the CFData \a data.
-
-    \sa fromRawCFData(), fromRawData(), toRawCFData(), toCFData()
-*/
-
-/*! \fn QByteArray QByteArray::fromRawCFData(CFDataRef data)
-    \since 5.3
-
-    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.
-
-    \sa fromCFData(), fromRawData(), toRawCFData(), toCFData()
-*/
-
-/*! \fn CFDataRef QByteArray::toCFData() const
-    \since 5.3
-
-    Creates a CFData from a QByteArray. The caller owns the CFData object
-    and is responsible for releasing it.
-
-    \sa toRawCFData(), fromCFData(), fromRawCFData(), fromRawData()
-*/
-
-/*! \fn CFDataRef QByteArray::toRawCFData() const
-    \since 5.3
-
-    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.
-
-    \sa toCFData(), fromRawCFData(), fromCFData(), fromRawData()
-*/
-
-/*! \fn QByteArray QByteArray::fromNSData(const NSData *data)
-    \since 5.3
-
-    Constructs a new QByteArray containing a copy of the NSData \a data.
-
-    \sa fromRawNSData(), fromRawData(), toNSData(), toRawNSData()
-*/
-
-/*! \fn QByteArray QByteArray::fromRawNSData(const NSData *data)
-    \since 5.3
-
-    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.
-
-    \sa fromNSData(), fromRawData(), toRawNSData(), toNSData()
-*/
-
-/*! \fn NSData QByteArray::toNSData() const
-    \since 5.3
-
-    Creates a NSData from a QByteArray. The NSData object is autoreleased.
-
-    \sa fromNSData(), fromRawNSData(), fromRawData(), toRawNSData()
-*/
-
-/*! \fn NSData QByteArray::toRawNSData() const
-    \since 5.3
-
-    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.
-
-    \sa fromRawNSData(), fromNSData(), fromRawData(), toNSData()
-*/
-
 static inline bool q_strchr(const char str[], char chr)
 {
     if (!str) return false;
diff --git a/src/corelib/tools/qbytearray_mac.mm b/src/corelib/tools/qbytearray_mac.mm
index 9386a966f0..aada473f92 100644
--- a/src/corelib/tools/qbytearray_mac.mm
+++ b/src/corelib/tools/qbytearray_mac.mm
@@ -44,6 +44,13 @@
 
 QT_BEGIN_NAMESPACE
 
+/*! \fn QByteArray QByteArray::fromCFData(CFDataRef data)
+    \since 5.3
+
+    Constructs a new QByteArray containing a copy of the CFData \a data.
+
+    \sa fromRawCFData(), fromRawData(), toRawCFData(), toCFData()
+*/
 QByteArray QByteArray::fromCFData(CFDataRef data)
 {
     if (!data)
@@ -52,6 +59,18 @@ QByteArray QByteArray::fromCFData(CFDataRef data)
     return QByteArray(reinterpret_cast<const char *>(CFDataGetBytePtr(data)), CFDataGetLength(data));
 }
 
+/*! \fn QByteArray QByteArray::fromRawCFData(CFDataRef data)
+    \since 5.3
+
+    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.
+
+    \sa fromCFData(), fromRawData(), toRawCFData(), toCFData()
+*/
 QByteArray QByteArray::fromRawCFData(CFDataRef data)
 {
     if (!data)
@@ -60,17 +79,45 @@ QByteArray QByteArray::fromRawCFData(CFDataRef data)
     return QByteArray::fromRawData(reinterpret_cast<const char *>(CFDataGetBytePtr(data)), CFDataGetLength(data));
 }
 
+/*! \fn CFDataRef QByteArray::toCFData() const
+    \since 5.3
+
+    Creates a CFData from a QByteArray. The caller owns the CFData object
+    and is responsible for releasing it.
+
+    \sa toRawCFData(), fromCFData(), fromRawCFData(), fromRawData()
+*/
 CFDataRef QByteArray::toCFData() const
 {
     return CFDataCreate(kCFAllocatorDefault, reinterpret_cast<const UInt8 *>(data()), length());
 }
 
+/*! \fn CFDataRef QByteArray::toRawCFData() const
+    \since 5.3
+
+    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.
+
+    \sa toCFData(), fromRawCFData(), fromCFData(), fromRawData()
+*/
+
 CFDataRef QByteArray::toRawCFData() const
 {
     return CFDataCreateWithBytesNoCopy(kCFAllocatorDefault, reinterpret_cast<const UInt8 *>(data()),
                     length(), kCFAllocatorNull);
 }
 
+/*! \fn QByteArray QByteArray::fromNSData(const NSData *data)
+    \since 5.3
+
+    Constructs a new QByteArray containing a copy of the NSData \a data.
+
+    \sa fromRawNSData(), fromRawData(), toNSData(), toRawNSData()
+*/
 QByteArray QByteArray::fromNSData(const NSData *data)
 {
     if (!data)
@@ -78,6 +125,18 @@ QByteArray QByteArray::fromNSData(const NSData *data)
     return QByteArray(reinterpret_cast<const char *>([data bytes]), [data length]);
 }
 
+/*! \fn QByteArray QByteArray::fromRawNSData(const NSData *data)
+    \since 5.3
+
+    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.
+
+    \sa fromNSData(), fromRawData(), toRawNSData(), toNSData()
+*/
 QByteArray QByteArray::fromRawNSData(const NSData *data)
 {
     if (!data)
@@ -85,11 +144,30 @@ QByteArray QByteArray::fromRawNSData(const NSData *data)
     return QByteArray::fromRawData(reinterpret_cast<const char *>([data bytes]), [data length]);
 }
 
+/*! \fn NSData QByteArray::toNSData() const
+    \since 5.3
+
+    Creates a NSData from a QByteArray. The NSData object is autoreleased.
+
+    \sa fromNSData(), fromRawNSData(), fromRawData(), toRawNSData()
+*/
 NSData *QByteArray::toNSData() const
 {
     return [NSData dataWithBytes:constData() length:size()];
 }
 
+/*! \fn NSData QByteArray::toRawNSData() const
+    \since 5.3
+
+    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.
+
+    \sa fromRawNSData(), fromNSData(), fromRawData(), toNSData()
+*/
 NSData *QByteArray::toRawNSData() const
 {
     // const_cast is fine here because NSData is immutable thus will never modify bytes we're giving it
diff --git a/src/corelib/tools/qdatetime.cpp b/src/corelib/tools/qdatetime.cpp
index 9aba68eef3..5dbf68fc81 100644
--- a/src/corelib/tools/qdatetime.cpp
+++ b/src/corelib/tools/qdatetime.cpp
@@ -4089,39 +4089,6 @@ qint64 QDateTime::currentMSecsSinceEpoch() Q_DECL_NOTHROW
 #error "What system is this?"
 #endif
 
-/*! \fn QDateTime QDateTime::fromCFDate(CFDateRef date)
-    \since 5.5
-
-    Constructs a new QDateTime containing a copy of the CFDate \a date.
-
-    \sa toCFDate()
-*/
-
-/*! \fn CFDateRef QDateTime::toCFDate() const
-    \since 5.5
-
-    Creates a CFDate from a QDateTime. The caller owns the CFDate object
-    and is responsible for releasing it.
-
-    \sa fromCFDate()
-*/
-
-/*! \fn QDateTime QDateTime::fromNSDate(const NSDate *date)
-    \since 5.5
-
-    Constructs a new QDateTime containing a copy of the NSDate \a date.
-
-    \sa toNSDate()
-*/
-
-/*! \fn NSDate QDateTime::toNSDate() const
-    \since 5.5
-
-    Creates an NSDate from a QDateTime. The NSDate object is autoreleased.
-
-    \sa fromNSDate()
-*/
-
 /*!
   \since 4.2
 
diff --git a/src/corelib/tools/qdatetime_mac.mm b/src/corelib/tools/qdatetime_mac.mm
index d61ea28636..c03c57d9f1 100644
--- a/src/corelib/tools/qdatetime_mac.mm
+++ b/src/corelib/tools/qdatetime_mac.mm
@@ -44,6 +44,13 @@
 
 QT_BEGIN_NAMESPACE
 
+/*! \fn QDateTime QDateTime::fromCFDate(CFDateRef date)
+    \since 5.5
+
+    Constructs a new QDateTime containing a copy of the CFDate \a date.
+
+    \sa toCFDate()
+*/
 QDateTime QDateTime::fromCFDate(CFDateRef date)
 {
     if (!date)
@@ -52,12 +59,27 @@ QDateTime QDateTime::fromCFDate(CFDateRef date)
                                                     + kCFAbsoluteTimeIntervalSince1970) * 1000));
 }
 
+/*! \fn CFDateRef QDateTime::toCFDate() const
+    \since 5.5
+
+    Creates a CFDate from a QDateTime. The caller owns the CFDate object
+    and is responsible for releasing it.
+
+    \sa fromCFDate()
+*/
 CFDateRef QDateTime::toCFDate() const
 {
     return CFDateCreate(kCFAllocatorDefault, (static_cast<CFAbsoluteTime>(toMSecsSinceEpoch())
                                                     / 1000) - kCFAbsoluteTimeIntervalSince1970);
 }
 
+/*! \fn QDateTime QDateTime::fromNSDate(const NSDate *date)
+    \since 5.5
+
+    Constructs a new QDateTime containing a copy of the NSDate \a date.
+
+    \sa toNSDate()
+*/
 QDateTime QDateTime::fromNSDate(const NSDate *date)
 {
     if (!date)
@@ -65,6 +87,13 @@ QDateTime QDateTime::fromNSDate(const NSDate *date)
     return QDateTime::fromMSecsSinceEpoch(static_cast<qint64>([date timeIntervalSince1970] * 1000));
 }
 
+/*! \fn NSDate QDateTime::toNSDate() const
+    \since 5.5
+
+    Creates an NSDate from a QDateTime. The NSDate object is autoreleased.
+
+    \sa fromNSDate()
+*/
 NSDate *QDateTime::toNSDate() const
 {
     return [NSDate
diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp
index accdb83608..92d187c3ec 100644
--- a/src/corelib/tools/qstring.cpp
+++ b/src/corelib/tools/qstring.cpp
@@ -7938,40 +7938,6 @@ QString QString::multiArg(int numArgs, const QString **args) const
     return result;
 }
 
-
-/*! \fn QString QString::fromCFString(CFStringRef string)
-    \since 5.2
-
-    Constructs a new QString containing a copy of the \a string CFString.
-
-    \note this function is only available on OS X and iOS.
-*/
-
-/*! \fn CFStringRef QString::toCFString() const
-    \since 5.2
-
-    Creates a CFString from a QString. The caller owns the CFString and is
-    responsible for releasing it.
-
-    \note this function is only available on OS X and iOS.
-*/
-
-/*! \fn QString QString::fromNSString(const NSString *string)
-    \since 5.2
-
-    Constructs a new QString containing a copy of the \a string NSString.
-
-    \note this function is only available on OS X and iOS.
-*/
-
-/*! \fn NSString QString::toNSString() const
-    \since 5.2
-
-    Creates a NSString from a QString. The NSString is autoreleased.
-
-    \note this function is only available on OS X and iOS.
-*/
-
 /*! \fn bool QString::isSimpleText() const
 
     \internal
diff --git a/src/corelib/tools/qstring_mac.mm b/src/corelib/tools/qstring_mac.mm
index 7b3d6b53c0..81cbb91e6c 100644
--- a/src/corelib/tools/qstring_mac.mm
+++ b/src/corelib/tools/qstring_mac.mm
@@ -43,6 +43,13 @@
 
 QT_BEGIN_NAMESPACE
 
+/*! \fn QString QString::fromCFString(CFStringRef string)
+    \since 5.2
+
+    Constructs a new QString containing a copy of the \a string CFString.
+
+    \note this function is only available on OS X and iOS.
+*/
 QString QString::fromCFString(CFStringRef string)
 {
     if (!string)
@@ -60,11 +67,26 @@ QString QString::fromCFString(CFStringRef string)
     return ret;
 }
 
+/*! \fn CFStringRef QString::toCFString() const
+    \since 5.2
+
+    Creates a CFString from a QString. The caller owns the CFString and is
+    responsible for releasing it.
+
+    \note this function is only available on OS X and iOS.
+*/
 CFStringRef QString::toCFString() const
 {
     return CFStringCreateWithCharacters(0, reinterpret_cast<const UniChar *>(unicode()), length());
 }
 
+/*! \fn QString QString::fromNSString(const NSString *string)
+    \since 5.2
+
+    Constructs a new QString containing a copy of the \a string NSString.
+
+    \note this function is only available on OS X and iOS.
+*/
 QString QString::fromNSString(const NSString *string)
 {
     if (!string)
@@ -75,6 +97,13 @@ QString QString::fromNSString(const NSString *string)
    return qstring;
 }
 
+/*! \fn NSString QString::toNSString() const
+    \since 5.2
+
+    Creates a NSString from a QString. The NSString is autoreleased.
+
+    \note this function is only available on OS X and iOS.
+*/
 NSString *QString::toNSString() const
 {
     return [NSString stringWithCharacters: reinterpret_cast<const UniChar*>(unicode()) length: length()];