Doc: Fix documentation warnings for Qt Mac Extras

Fix namespacing for \fn commands, and mark deprecated functions correctly
with \obsolete.

QDoc doesn't see Qt's include paths for this module; work around
parsing issues by omitting include statements with the Q_CLANG_QDOC
macro.

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

3 files changed, 18 insertions, 6 deletions

diff --git a/src/macextras/qmacfunctions.mm b/src/macextras/qmacfunctions.mm
index 60cb733..afd704c 100644
--- a/src/macextras/qmacfunctions.mm
+++ b/src/macextras/qmacfunctions.mm
@@ -64,6 +64,10 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \fn CGContextRef QtMac::currentCGContext()
+    \obsolete
+
+    Use \c UIGraphicsGetCurrentContext() or
+    \c NSGraphicsContext.currentContext.CGContext instead.
 
     Returns the current CoreGraphics context.
 */
@@ -101,6 +105,7 @@ QByteArray fromNSData(const NSData *data)
 #if QT_DEPRECATED_SINCE(5, 12)
 /*!
     \fn CGImageRef QtMac::toCGImageRef(const QPixmap &pixmap)
+    \obsolete Use QPixmap::toImage() and QImage::toCGImage() instead.
 
     Creates a \c CGImageRef equivalent to the QPixmap \a pixmap. Returns the \c CGImageRef handle.
 
diff --git a/src/macextras/qmacfunctions_ios.mm b/src/macextras/qmacfunctions_ios.mm
index 0aaada8..e80d71a 100644
--- a/src/macextras/qmacfunctions_ios.mm
+++ b/src/macextras/qmacfunctions_ios.mm
@@ -54,7 +54,8 @@ CGContextRef currentCGContext()
 }
 
 /*!
-    \fn void QtMac::setApplicationIconBadgeNumber(int number)
+    \fn void setApplicationIconBadgeNumber(int number)
+    \obsolete Use \c {UIApplication.sharedApplication.applicationIconBadgeNumber} instead.
 
     Sets the value shown on the application icon a.k.a badge to \a number.
 
@@ -68,7 +69,8 @@ void setApplicationIconBadgeNumber(int number)
 }
 
 /*!
-    \fn int QtMac::applicationIconBadgeNumber()
+    \fn int applicationIconBadgeNumber()
+    \obsolete Use \c {UIApplication.sharedApplication.applicationIconBadgeNumber} instead.
 
     Returns the value of the application icon a.k.a badge.
 
diff --git a/src/macextras/qmacfunctions_mac.mm b/src/macextras/qmacfunctions_mac.mm
index 2e66e23..03cbcab 100644
--- a/src/macextras/qmacfunctions_mac.mm
+++ b/src/macextras/qmacfunctions_mac.mm
@@ -41,6 +41,7 @@
 #import <AppKit/NSApplication.h>
 
 #include "qmacfunctions.h"
+#ifndef Q_CLANG_QDOC
 #include "qmacfunctions_p.h"
 
 #include <QtCore/QString>
@@ -51,6 +52,7 @@
 #include <QtWidgets/QMenuBar>
 #include <qpa/qplatformmenu.h>
 #endif
+#endif // Q_CLANG_QDOC
 
 QT_BEGIN_NAMESPACE
 
@@ -59,7 +61,8 @@ namespace QtMac
 
 #if QT_DEPRECATED_SINCE(5, 12)
 /*!
-    \fn NSImage* QtMac::toNSImage(const QPixmap &pixmap)
+    \fn NSImage *toNSImage(const QPixmap &pixmap)
+    \obsolete Use QPixmap::toImage and QImage::toCGImage instead.
 
     Creates an \c NSImage equivalent to the QPixmap \a pixmap. Returns the \c NSImage handle.
 
@@ -82,7 +85,7 @@ NSImage* toNSImage(const QPixmap &pixmap)
 
 #if QT_VERSION >= QT_VERSION_CHECK(5, 0, 0)
 /*!
-    \fn bool QtMac::isMainWindow(QWindow *window)
+    \fn bool isMainWindow(QWindow *window)
 
     Returns whether the given QWindow \a window is the application's main window
 */
@@ -104,7 +107,8 @@ CGContextRef currentCGContext()
 }
 
 /*!
-    \fn void QtMac::setBadgeLabelText(const QString &text)
+    \fn void setBadgeLabelText(const QString &text)
+    \obsolete Use \c {NSApp.dockTile.badgeLabel} instead.
 
     Sets the \a text shown on the application icon a.k.a badge.
 
@@ -118,7 +122,8 @@ void setBadgeLabelText(const QString &text)
 }
 
 /*!
-    \fn QString QtMac::badgeLabelText()
+    \fn QString badgeLabelText()
+    \obsolete Use \c {NSApp.dockTile.badgeLabel} instead.
 
     Returns the text of the application icon a.k.a badge.