Doc: Create documentation structure for Qt Mac Extrasv5.2.0-alpha1

Create documentation structure for the module
    - Module qdocconf
    - Documentation pages for module index, namespace/classes,
      examples (not much content yet)

Other doc-related changes
    - Enable running 'make docs' on all platforms
    - Move examples under examples/macextras for a clean
      installing to QT_INSTALL_EXAMPLES
    - Ensure documented classes use correct \inmodule and
      \since commands
    - Add \namespace QtMac
    - Other minor fixes

Change-Id: I1376d68fcd7ab324a5d3355f1d15914092900e5b
Reviewed-by: Morten Johan Sørvig <morten.sorvig@digia.com>

22 files changed, 309 insertions, 17 deletions

diff --git a/examples/examples.pro b/examples/examples.pro
index 8fe1d13..f23b00b 100644
--- a/examples/examples.pro
+++ b/examples/examples.pro
@@ -1,5 +1,2 @@
 TEMPLATE = subdirs
-
-mac:SUBDIRS = macfunctions
-mac:!ios:SUBDIRS += embeddedqwindow \
-          macpasteboardmime
+mac:SUBDIRS = macextras
diff --git a/examples/embeddedqwindow/embeddedqwindow.pro b/examples/macextras/embeddedqwindow/embeddedqwindow.pro
index 022a614..022a614 100644
--- a/examples/embeddedqwindow/embeddedqwindow.pro
+++ b/examples/macextras/embeddedqwindow/embeddedqwindow.pro
diff --git a/examples/embeddedqwindow/main.mm b/examples/macextras/embeddedqwindow/main.mm
index f24533b..f24533b 100644
--- a/examples/embeddedqwindow/main.mm
+++ b/examples/macextras/embeddedqwindow/main.mm
diff --git a/examples/embeddedqwindow/window.cpp b/examples/macextras/embeddedqwindow/window.cpp
index 1868591..1868591 100644
--- a/examples/embeddedqwindow/window.cpp
+++ b/examples/macextras/embeddedqwindow/window.cpp
diff --git a/examples/embeddedqwindow/window.h b/examples/macextras/embeddedqwindow/window.h
index cdd6ebd..cdd6ebd 100644
--- a/examples/embeddedqwindow/window.h
+++ b/examples/macextras/embeddedqwindow/window.h
diff --git a/examples/macextras/macextras.pro b/examples/macextras/macextras.pro
new file mode 100644
index 0000000..8fe1d13
--- /dev/null
+++ b/examples/macextras/macextras.pro
@@ -0,0 +1,5 @@
+TEMPLATE = subdirs
+
+mac:SUBDIRS = macfunctions
+mac:!ios:SUBDIRS += embeddedqwindow \
+          macpasteboardmime
diff --git a/examples/macfunctions/macfunctions.pro b/examples/macextras/macfunctions/macfunctions.pro
index 8d11880..8d11880 100644
--- a/examples/macfunctions/macfunctions.pro
+++ b/examples/macextras/macfunctions/macfunctions.pro
diff --git a/examples/macfunctions/macfunctions.qrc b/examples/macextras/macfunctions/macfunctions.qrc
index 04a9419..04a9419 100644
--- a/examples/macfunctions/macfunctions.qrc
+++ b/examples/macextras/macfunctions/macfunctions.qrc
diff --git a/examples/macfunctions/main.cpp b/examples/macextras/macfunctions/main.cpp
index a1563ba..a1563ba 100644
--- a/examples/macfunctions/main.cpp
+++ b/examples/macextras/macfunctions/main.cpp
diff --git a/examples/macfunctions/qtlogo.png b/examples/macextras/macfunctions/qtlogo.png
index d75936b..d75936b 100644
--- a/examples/macfunctions/qtlogo.png
+++ b/examples/macextras/macfunctions/qtlogo.png
diff --git a/examples/macpasteboardmime/macpasteboardmime.pro b/examples/macextras/macpasteboardmime/macpasteboardmime.pro
index 3ce4cd4..3ce4cd4 100644
--- a/examples/macpasteboardmime/macpasteboardmime.pro
+++ b/examples/macextras/macpasteboardmime/macpasteboardmime.pro
diff --git a/examples/macpasteboardmime/main.cpp b/examples/macextras/macpasteboardmime/main.cpp
index 4d3063a..4d3063a 100644
--- a/examples/macpasteboardmime/main.cpp
+++ b/examples/macextras/macpasteboardmime/main.cpp
diff --git a/src/macextras/doc/qtmacextras.qdocconf b/src/macextras/doc/qtmacextras.qdocconf
new file mode 100644
index 0000000..1fc3c4d
--- /dev/null
+++ b/src/macextras/doc/qtmacextras.qdocconf
@@ -0,0 +1,42 @@
+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+
+project                 = QtMacExtras
+description             = Qt Mac Extras Reference Documentation
+url                     = http://qt-project.org/doc/qt-$QT_VER/qtmacextras
+version                 = $QT_VERSION
+
+exampledirs += ../../../examples/macextras \
+               snippets
+
+examplesinstallpath     = macextras
+
+headerdirs = ..
+sourcedirs = ..
+imagedirs += images
+
+Cpp.ignoretokens += Q_MACEXTRAS_EXPORT
+
+depends += qtcore qtgui qtwidgets qtdoc
+
+qhp.projects = QtMacExtras
+
+qhp.QtMacExtras.file = qtmacextras.qhp
+
+qhp.QtMacExtras.namespace = org.qt-project.qtmacextras.$QT_VERSION_TAG
+
+qhp.QtMacExtras.indexTitle = Qt Mac Extras
+qhp.QtMacExtras.indexRoot =
+
+qhp.QtMacExtras.filterAttributes = qtmacextras $QT_VERSION qtrefdoc
+qhp.QtMacExtras.customFilters.Qt.name = QtMacExtras $QT_VERSION
+qhp.QtMacExtras.customFilters.Qt.filterAttributes = qtmacextras $QT_VERSION
+
+qhp.QtMacExtras.virtualFolder = qtmacextras
+qhp.QtMacExtras.subprojects = classes examples
+qhp.QtMacExtras.subprojects.classes.title = C++ Classes and Namespaces
+qhp.QtMacExtras.subprojects.classes.indexTitle = Qt Mac Extras C++ Classes
+qhp.QtMacExtras.subprojects.classes.selectors = class function namespace fake:headerfile
+qhp.QtMacExtras.subprojects.classes.sortPages = true
+qhp.QtMacExtras.subprojects.examples.title = Examples
+qhp.QtMacExtras.subprojects.examples.indexTitle = Qt Mac Extras Examples
+qhp.QtMacExtras.subprojects.examples.selectors = fake:example
diff --git a/src/macextras/doc/snippets/code/use-qtmacextras.cpp b/src/macextras/doc/snippets/code/use-qtmacextras.cpp
new file mode 100644
index 0000000..b138e0c
--- /dev/null
+++ b/src/macextras/doc/snippets/code/use-qtmacextras.cpp
@@ -0,0 +1,43 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [include]
+#include <QtMacExtras>
+//! [include]
diff --git a/src/macextras/doc/snippets/code/use-qtmacextras.pro b/src/macextras/doc/snippets/code/use-qtmacextras.pro
new file mode 100644
index 0000000..b0496bb
--- /dev/null
+++ b/src/macextras/doc/snippets/code/use-qtmacextras.pro
@@ -0,0 +1,3 @@
+#! [link]
+QT += macextras
+#! [link]
diff --git a/src/macextras/doc/src/qtmacextras-examples.qdoc b/src/macextras/doc/src/qtmacextras-examples.qdoc
new file mode 100644
index 0000000..4076278
--- /dev/null
+++ b/src/macextras/doc/src/qtmacextras-examples.qdoc
@@ -0,0 +1,52 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+
+\group examples-qtmacextras
+\title Qt Mac Extras Examples
+\brief Examples for the Qt Mac Extras module.
+\ingroup all-examples
+
+Here is a list of example applications demonstrating the functionality
+provided by the \l{Qt Mac Extras} module.
+
+\note These examples work only on \l{Qt for Mac OS X}{Mac OS X} operating system.
+*/
diff --git a/src/macextras/doc/src/qtmacextras-index.qdoc b/src/macextras/doc/src/qtmacextras-index.qdoc
new file mode 100644
index 0000000..f0af333
--- /dev/null
+++ b/src/macextras/doc/src/qtmacextras-index.qdoc
@@ -0,0 +1,71 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtmacextras-index.html
+    \title Qt Mac Extras
+    \brief Provides functionality specific to Mac OS X and iOS operating systems.
+
+    Qt Mac Extras provide classes and functions that enable you to use
+    miscellaneous functionality specific to Mac OS X and iOS operating systems.
+
+    \section1 Getting Started
+
+    To include the definitions of the module's classes and functions, use the
+    following include statement:
+
+    \snippet code/use-qtmacextras.cpp include
+
+    To link against the module, add this line to your qmake .pro file:
+
+    \snippet code/use-qtmacextras.pro link
+
+    \section1 Examples
+
+    \list
+    \li \l {Qt Mac Extras Examples}
+    \endlist
+
+    \section1 API Reference
+
+    \list
+    \li \l {Qt Mac Extras C++ Classes}{C++ Classes and Namespaces}
+    \endlist
+*/
diff --git a/src/macextras/doc/src/qtmacextras-module-cpp.qdoc b/src/macextras/doc/src/qtmacextras-module-cpp.qdoc
new file mode 100644
index 0000000..f636fdf
--- /dev/null
+++ b/src/macextras/doc/src/qtmacextras-module-cpp.qdoc
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+**     of its contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \module QtMacExtras
+    \title Qt Mac Extras C++ Classes
+    \brief Provides classes and functions specific to Mac OS X and iOS operating systems.
+
+    \ingroup modules
+    \ingroup technology-apis
+    \qtvariable macextras
+
+    \sa QMacCocoaViewContainer, QMacNativeWidget
+*/
diff --git a/src/macextras/macextras.pro b/src/macextras/macextras.pro
index 12f00cd..acce83c 100644
--- a/src/macextras/macextras.pro
+++ b/src/macextras/macextras.pro
@@ -4,3 +4,4 @@ load(qt_build_config)
 QT_PRIVATE += gui-private core-private
 TARGET = QtMacExtras
 load(qt_module)
+QMAKE_DOCS = $$PWD/doc/qtmacextras.qdocconf
diff --git a/src/macextras/qmacfunctions.mm b/src/macextras/qmacfunctions.mm
index d843981..3484bbc 100644
--- a/src/macextras/qmacfunctions.mm
+++ b/src/macextras/qmacfunctions.mm
@@ -54,6 +54,13 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \namespace QtMac
+    \inmodule QtMacExtras
+    \since 5.2
+    \brief The QtMac namespace contains miscellaneous functionality specific to Mac OS X and iOS operating systems.
+    \inheaderfile QMacFunctions
+ */
 namespace QtMac
 {
 
diff --git a/src/macextras/qmacpasteboardmime.mm b/src/macextras/qmacpasteboardmime.mm
index ec8fa7e..ee51bfb 100644
--- a/src/macextras/qmacpasteboardmime.mm
+++ b/src/macextras/qmacpasteboardmime.mm
@@ -73,6 +73,8 @@ void qRegisterDraggedTypes(const QStringList &types)
 
 /*!
   \class QMacPasteboardMime
+  \inmodule QtMacExtras
+  \since 5.2
   \brief The QMacPasteboardMime class converts between a MIME type and a
   \l{http://developer.apple.com/macosx/uniformtypeidentifiers.html}{Uniform
   Type Identifier (UTI)} format.
@@ -89,17 +91,28 @@ void qRegisterDraggedTypes(const QStringList &types)
   A subclass of QMacPasteboardMime will automatically be registered, and active, upon instantiation.
 
   Qt has predefined support for the following UTIs:
-  \list
-    \i public.utf8-plain-text - converts to "text/plain"
-    \i public.utf16-plain-text - converts to "text/plain"
-    \i public.html - converts to "text/html"
-    \i public.url - converts to "text/uri-list"
-    \i public.file-url - converts to "text/uri-list"
-    \i public.tiff - converts to "application/x-qt-image"
-    \i public.vcard - converts to "text/plain"
-    \i com.apple.traditional-mac-plain-text - converts to "text/plain"
-    \i com.apple.pict - converts to "application/x-qt-image"
-  \endlist
+  \table
+    \header \li UTI
+            \li Converts to
+    \row \li \c public.utf8-plain-text
+         \li \c text/plain
+    \row \li \c public.utf16-plain-text
+         \li \c text/plain
+    \row \li \c public.html
+         \li \c text/html
+    \row \li \c public.url
+         \li \c text/uri-list
+    \row \li \c public.file-url
+         \li \c text/uri-list
+    \row \li \c public.tiff
+         \li \c application/x-qt-image
+    \row \li \c public.vcard
+         \li \c text/plain
+    \row \li \c com.apple.traditional-mac-plain-text
+         \li \c text/plain
+    \row \li \c com.apple.pict
+         \li \c application/x-qt-image
+    \endtable
 
   When working with MIME data, Qt will interate through all instances of QMacPasteboardMime to
   find an instance that can convert to, or from, a specific MIME type. It will do this by calling
diff --git a/src/src.pro b/src/src.pro
index 317df66..fd1ffb1 100644
--- a/src/src.pro
+++ b/src/src.pro
@@ -1,2 +1,9 @@
-TEMPLATE = subdirs
-mac:SUBDIRS += macextras
+mac {
+    TEMPLATE = subdirs
+    SUBDIRS += macextras
+}
+else {
+    # fake project for creating the documentation
+    TEMPLATE = aux
+    QMAKE_DOCS = $$PWD/macextras/doc/qtmacextras.qdocconf
+}