Document qtmacextras functions

This patch aims to provide the missing Qt Mac Extras documentation

The conversion functions (e.g. NSData <=> QByteArray) are not
documented because they will either be moved to QtCore or
removed from QtMacExtras since already present in QtCore

Change-Id: I364be524966b353602bcf88218d9bb81042497ff
Reviewed-by: Jake Petroules <jake.petroules@petroules.com>
Reviewed-by: Gabriel de Dietrich <gabriel.dedietrich@digia.com>

2 files changed, 39 insertions, 0 deletions

diff --git a/src/macextras/qmacfunctions_ios.mm b/src/macextras/qmacfunctions_ios.mm
index ddc6a03..fa83ce6 100644
--- a/src/macextras/qmacfunctions_ios.mm
+++ b/src/macextras/qmacfunctions_ios.mm
@@ -49,16 +49,31 @@ QT_BEGIN_NAMESPACE
 namespace QtMac
 {
 
+/*!
+    Returns the current CoreGraphics context.
+*/
 CGContextRef currentCGContext()
 {
     return UIGraphicsGetCurrentContext();
 }
 
+/*!
+    Sets the value shown on the application icon a.k.a badge.
+
+    Unlike its OS X counterpart, only numbers can be used.
+
+    \sa applicationIconBadgeNumber(), setBadgeLabelText()
+*/
 void setApplicationIconBadgeNumber(int number)
 {
     [[UIApplication sharedApplication] setApplicationIconBadgeNumber: number];
 }
 
+/*!
+    Returns the value of the application icon a.k.a badge.
+
+    \sa setApplicationIconBadgeNumber(), badgeLabelText()
+*/
 int applicationIconBadgeNumber()
 {
     return [[UIApplication sharedApplication] applicationIconBadgeNumber];
diff --git a/src/macextras/qmacfunctions_mac.mm b/src/macextras/qmacfunctions_mac.mm
index 9901314..88ebb61 100644
--- a/src/macextras/qmacfunctions_mac.mm
+++ b/src/macextras/qmacfunctions_mac.mm
@@ -57,6 +57,12 @@ QT_BEGIN_NAMESPACE
 namespace QtMac
 {
 
+/*!
+    Creates an \c NSImage equivalent to the QPixmap. Returns the \c NSImage handle.
+
+    It is the caller's responsibility to release the \c NSImage data
+    after use.
+*/
 NSImage* toNSImage(const QPixmap &pixmap)
 {
     NSBitmapImageRep *bitmapRep = [[NSBitmapImageRep alloc] initWithCGImage:toCGImageRef(pixmap)];
@@ -67,6 +73,9 @@ NSImage* toNSImage(const QPixmap &pixmap)
 }
 
 #if QT_VERSION >= QT_VERSION_CHECK(5, 0, 0)
+/*!
+    Returns whether the given QWindow is the application's main window
+*/
 bool isMainWindow(QWindow *window)
 {
     NSWindow *macWindow = static_cast<NSWindow*>(
@@ -78,16 +87,31 @@ bool isMainWindow(QWindow *window)
 }
 #endif
 
+/*!
+    Returns the current CoreGraphics context.
+*/
 CGContextRef currentCGContext()
 {
     return reinterpret_cast<CGContextRef>([[NSGraphicsContext currentContext] graphicsPort]);
 }
 
+/*!
+    Sets the text shown on the application icon a.k.a badge.
+
+    This is generally used with numbers (e.g. number of unread emails); it can also show a string.
+
+    \sa badgeLabelText()
+*/
 void setBadgeLabelText(const QString &text)
 {
     [[[NSApplication sharedApplication] dockTile] setBadgeLabel:toNSString(text)];
 }
 
+/*!
+    Returns the text of the application icon a.k.a badge.
+
+    \sa setBadgeText()
+*/
 QString badgeLabelText()
 {
     return fromNSString([[[NSApplication sharedApplication] dockTile] badgeLabel]);