Improve NFC documentation

1.) Extend the NFC overview page
2.) Ensure that snippets are compiled at all times
3.) Mark Qt 5.3 APIs using \since

Task-number: QTBUG-32401
Task-number: QTBUG-34978
Change-Id: I8928be3d7dd2c9de1314eb1ec6ed55c8d4301f4a
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Reviewed-by: Alex Blasche <alexander.blasche@digia.com>

13 files changed, 167 insertions, 78 deletions

diff --git a/examples/nfc/annotatedurl/annotatedurl.cpp b/examples/nfc/annotatedurl/annotatedurl.cpp
index 293decf7..f29045b6 100644
--- a/examples/nfc/annotatedurl/annotatedurl.cpp
+++ b/examples/nfc/annotatedurl/annotatedurl.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the QtNfc module.
@@ -63,8 +63,10 @@ AnnotatedUrl::~AnnotatedUrl()
 {
 }
 
+//! [handleMessage 1]
 void AnnotatedUrl::handleMessage(const QNdefMessage &message, QNearFieldTarget *target)
 {
+//! [handleMessage 1]
     Q_UNUSED(target);
 
     enum {
@@ -81,39 +83,40 @@ void AnnotatedUrl::handleMessage(const QNdefMessage &message, QNearFieldTarget *
     QUrl url;
     QPixmap pixmap;
 
+//! [handleMessage 2]
     foreach (const QNdefRecord &record, message) {
         if (record.isRecordType<QNdefNfcTextRecord>()) {
             QNdefNfcTextRecord textRecord(record);
 
+            title = textRecord.text();
             QLocale locale(textRecord.locale());
-
+//! [handleMessage 2]
             // already found best match
             if (bestMatch == MatchedLanguageAndCountry) {
                 // do nothing
             } else if (bestMatch <= MatchedLanguage && locale == defaultLocale) {
-                title = textRecord.text();
                 bestMatch = MatchedLanguageAndCountry;
             } else if (bestMatch <= MatchedEnglish &&
                        locale.language() == defaultLocale.language()) {
-                title = textRecord.text();
                 bestMatch = MatchedLanguage;
             } else if (bestMatch <= MatchedFirst && locale.language() == QLocale::English) {
-                title = textRecord.text();
                 bestMatch = MatchedEnglish;
             } else if (bestMatch == MatchedNone) {
-                title = textRecord.text();
                 bestMatch = MatchedFirst;
             }
+//! [handleMessage 3]
         } else if (record.isRecordType<QNdefNfcUriRecord>()) {
             QNdefNfcUriRecord uriRecord(record);
 
             url = uriRecord.uri();
+//! [handleMessage 3]
         } else if (record.typeNameFormat() == QNdefRecord::Mime &&
                    record.type().startsWith("image/")) {
             pixmap = QPixmap::fromImage(QImage::fromData(record.payload()));
+//! [handleMessage 4]
         }
     }
 
     emit annotatedUrl(url, title, pixmap);
 }
-
+//! [handleMessage 4]
diff --git a/examples/nfc/annotatedurl/main.cpp b/examples/nfc/annotatedurl/main.cpp
index c669e57b..351f33bf 100644
--- a/examples/nfc/annotatedurl/main.cpp
+++ b/examples/nfc/annotatedurl/main.cpp
@@ -57,6 +57,7 @@ int main(int argc, char *argv[])
     QApplication a(argc, argv);
     MainWindow mainWindow;
 
+    //! [QNearFieldManager register handler]
     QNearFieldManager manager;
     AnnotatedUrl annotatedUrl;
 
@@ -66,6 +67,7 @@ int main(int argc, char *argv[])
     filter.appendRecord<QNdefNfcUriRecord>();
     manager.registerNdefMessageHandler(filter, &annotatedUrl,
                                        SLOT(handleMessage(QNdefMessage,QNearFieldTarget*)));
+    //! [QNearFieldManager register handler]
 
     QObject::connect(&annotatedUrl, SIGNAL(annotatedUrl(QUrl,QString,QPixmap)),
                      &mainWindow, SLOT(displayAnnotatedUrl(QUrl,QString,QPixmap)));
diff --git a/examples/nfc/ndefeditor/mainwindow.cpp b/examples/nfc/ndefeditor/mainwindow.cpp
index df8f758c..fedb0866 100644
--- a/examples/nfc/ndefeditor/mainwindow.cpp
+++ b/examples/nfc/ndefeditor/mainwindow.cpp
@@ -120,8 +120,7 @@ void addRecord(Ui::MainWindow *ui, const QNdefRecord &record = QNdefRecord())
 }
 
 MainWindow::MainWindow(QWidget *parent)
-:   QMainWindow(parent), ui(new Ui::MainWindow), m_manager(new QNearFieldManager(this)),
-    m_touchAction(NoAction)
+:   QMainWindow(parent), ui(new Ui::MainWindow), m_touchAction(NoAction)
 {
     ui->setupUi(this);
 
@@ -135,10 +134,13 @@ MainWindow::MainWindow(QWidget *parent)
     QVBoxLayout *vbox = new QVBoxLayout;
     ui->scrollAreaWidgetContents->setLayout(vbox);
 
+    //! [QNearFieldManager init]
+    m_manager = new QNearFieldManager(this);
     connect(m_manager, SIGNAL(targetDetected(QNearFieldTarget*)),
             this, SLOT(targetDetected(QNearFieldTarget*)));
     connect(m_manager, SIGNAL(targetLost(QNearFieldTarget*)),
             this, SLOT(targetLost(QNearFieldTarget*)));
+    //! [QNearFieldManager init]
 }
 
 MainWindow::~MainWindow()
@@ -205,7 +207,9 @@ void MainWindow::touchReceive()
     m_touchAction = ReadNdef;
 
     m_manager->setTargetAccessModes(QNearFieldManager::NdefReadTargetAccess);
+    //! [QNearFieldManager start detection]
     m_manager->startTargetDetection();
+    //! [QNearFieldManager start detection]
 }
 
 void MainWindow::touchStore()
@@ -218,6 +222,7 @@ void MainWindow::touchStore()
     m_manager->startTargetDetection();
 }
 
+//! [QNearFieldTarget detected]
 void MainWindow::targetDetected(QNearFieldTarget *target)
 {
     switch (m_touchAction) {
@@ -240,11 +245,14 @@ void MainWindow::targetDetected(QNearFieldTarget *target)
         break;
     }
 }
+//! [QNearFieldTarget detected]
 
+//! [QNearFieldTarget lost]
 void MainWindow::targetLost(QNearFieldTarget *target)
 {
     target->deleteLater();
 }
+//! [QNearFieldTarget lost]
 
 void MainWindow::ndefMessageRead(const QNdefMessage &message)
 {
@@ -267,7 +275,9 @@ void MainWindow::ndefMessageRead(const QNdefMessage &message)
 
     ui->status->setStyleSheet(QString());
     m_manager->setTargetAccessModes(QNearFieldManager::NoTargetAccess);
+    //! [QNearFieldManager stop detection]
     m_manager->stopTargetDetection();
+    //! [QNearFieldManager stop detection]
     m_request = QNearFieldTarget::RequestId();
     ui->statusBar->clearMessage();
 }
diff --git a/src/imports/nfc/qdeclarativenearfield.cpp b/src/imports/nfc/qdeclarativenearfield.cpp
index 673c9a0d..b1aeced7 100644
--- a/src/imports/nfc/qdeclarativenearfield.cpp
+++ b/src/imports/nfc/qdeclarativenearfield.cpp
@@ -69,14 +69,7 @@
     and \l orderMatch properties to match the required NDEF messages.  Once an NDEF message is
     successfully read from a tag the \l messageRecords property is updated.
 
-    \code
-        NearField {
-            filter: [ NdefFilter { type: "U"; typeNameFormat: NdefRecord.NfcRtd; minimum: 1; maximum: 1 } ]
-            orderMatch: false
-
-            onMessageRecordsChanged: displayMessage()
-        }
-    \endcode
+    \snippet doc_src_qtnfc.qml QML register for messages
 */
 
 /*!
diff --git a/src/nfc/doc/snippets/doc_src_qtnfc.pro b/src/nfc/doc/snippets/doc_src_qtnfc.pro
deleted file mode 100644
index 5730e227..00000000
--- a/src/nfc/doc/snippets/doc_src_qtnfc.pro
+++ /dev/null
@@ -1,51 +0,0 @@
-#****************************************************************************
-#*
-#* Copyright (C) 2013 Aaron McCarthy <mccarthy.aaron@gmail.com>
-#* 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$
-#*
-#***************************************************************************/
-
-#! [project modification]
-QT += nfc
-#! [project modification]
-
-SOURCES += main.cpp \
-           doc_src_qtnfc.cpp \
-           nfc.cpp \
-           foorecord.cpp
-
-HEADERS += foorecord.h
diff --git a/src/nfc/doc/snippets/doc_src_qtnfc.qml b/src/nfc/doc/snippets/doc_src_qtnfc.qml
index 6c4d892d..427c24c6 100644
--- a/src/nfc/doc/snippets/doc_src_qtnfc.qml
+++ b/src/nfc/doc/snippets/doc_src_qtnfc.qml
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2013 Aaron McCarthy <mccarthy.aaron@gmail.com>
+** Copyright (C) 2014 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.
@@ -42,4 +43,13 @@
 import QtNfc 5.2
 //! [import]
 
-Item { }
+Item {
+//! [QML register for messages]
+    NearField {
+        filter: [ NdefFilter { type: "U"; typeNameFormat: NdefRecord.NfcRtd; minimum: 1; maximum: 1 } ]
+        orderMatch: false
+
+        onMessageRecordsChanged: displayMessage()
+    }
+//! [QML register for messages]
+}
diff --git a/src/nfc/doc/snippets/snippets.pro b/src/nfc/doc/snippets/snippets.pro
new file mode 100644
index 00000000..437782e4
--- /dev/null
+++ b/src/nfc/doc/snippets/snippets.pro
@@ -0,0 +1,13 @@
+TEMPLATE = app
+TARGET = nfc_cppsnippet
+QT = core
+#! [project modification]
+QT += nfc
+#! [project modification]
+
+SOURCES += main.cpp \
+           doc_src_qtnfc.cpp \
+           nfc.cpp \
+           foorecord.cpp
+
+HEADERS += foorecord.h
diff --git a/src/nfc/doc/src/nfc-cpp.qdoc b/src/nfc/doc/src/nfc-cpp.qdoc
index 4df93e69..cbb07e0c 100644
--- a/src/nfc/doc/src/nfc-cpp.qdoc
+++ b/src/nfc/doc/src/nfc-cpp.qdoc
@@ -38,6 +38,6 @@ The \l{Qt NFC} C++ API enables an application to access NFC Forum Tags.
 To use the C++ library in your application, add the following configuration
 option to your \c .pro file:
 
-\snippet doc_src_qtnfc.pro project modification
+\snippet snippets.pro project modification
 */
 
diff --git a/src/nfc/doc/src/nfc-index.qdoc b/src/nfc/doc/src/nfc-index.qdoc
index 2ec40891..e82973d4 100644
--- a/src/nfc/doc/src/nfc-index.qdoc
+++ b/src/nfc/doc/src/nfc-index.qdoc
@@ -43,7 +43,7 @@ on NFC Forum Tags and sending tag specific commands.
 To use the C++ library in your application, add the following configuration
 option to your \c .pro file:
 
-\snippet doc_src_qtnfc.pro project modification
+\snippet snippets.pro project modification
 
 To use the classes of the module in your application you need the following
 import statement in your \c .qml file:
diff --git a/src/nfc/doc/src/nfc-overview.qdoc b/src/nfc/doc/src/nfc-overview.qdoc
index b7d029bb..b068dfb5 100644
--- a/src/nfc/doc/src/nfc-overview.qdoc
+++ b/src/nfc/doc/src/nfc-overview.qdoc
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2013 Aaron McCarthy <mccarthy.aaron@gmail.com>
+** Copyright (C) 2014 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.
@@ -36,14 +37,114 @@
 With the Qt NFC API typical use cases are:
 
 \list
-    \li Detect NFC tags entering and leaving the communication range.
-    \li Read and write NDEF message on NFC Forum Tags.
-    \li Register an NDEF message handler for a particular content type.
+    \li Detecting NFC tags.
+    \li Reading and writing NDEF messages.
+    \li Registering NDEF message handlers.
+    \li Sharing files and messages.
 \endlist
 
-The following sections describe how to use Qt NFC C++ classes for the above use cases.
+The following sections describe how to use Qt NFC C++ classes and QML types for the above use cases.
 
-\section1 Detect NFC tags entering and leaving communication range.
-\section1 Read and write an NDEF message on NFC Forum Tags.
-\section1 Register an NDEF message handler for a particular content type.
+\section1 C++ Overview
+
+The C++ API provides access to the full feature set of the Qt NFC API. This section introduces the
+major features available to developers.
+
+\section2 Detecting NFC Tags
+
+The \l QNearFieldManager class is responsible for the detection of new NFC tags coming
+into range of the device. The \l QNearFieldManager::targetDetected() and
+\l QNearFieldManager::targetLost() signals are emitted when
+a tag comes into or leaves the range. The passed \l QNearFieldTarget parameter acts
+as primary interaction point for each detected tag. The detection does not actually start though until
+\l QNearFieldManager::startTargetDetection() has been called.
+
+\snippet ndefeditor/mainwindow.cpp QNearFieldManager init
+\snippet ndefeditor/mainwindow.cpp QNearFieldManager start detection
+
+Finally the detection can be stopped:
+
+\snippet ndefeditor/mainwindow.cpp QNearFieldManager stop detection
+
+Although each \l QNearFieldTarget instance is owned by its related \l QNearFieldManager
+instance it can be beneficial to manually delete each instance. Otherwise they would continue to
+exist until the \l QNearFieldManager instance is deleted. The best way to do that would be in response
+to the \l QNearFieldManager::targetLost() signal:
+
+\snippet ndefeditor/mainwindow.cpp QNearFieldTarget lost
+
+\note The target object should only be deleted via deleteLater() if it is deleted inside the slot.
+
+\section2 Reading and Writing NDEF Messages
+
+The \l QNearFieldTarget instance returned by \l QNearFieldManager::targetDetected() signal
+is used to interact with the tag. Reading and writing a message is an asynchronous operation.
+The \l QNearFieldTarget::RequestId class associates individual operations and their results.
+
+\snippet ndefeditor/mainwindow.cpp QNearFieldTarget detected
+
+Once the \l QNearFieldTarget::readNdefMessages() request was successfully processed, the
+\l QNearFieldTarget::ndefMessageRead() signal is emitted. Each returned \l QNdefMessage
+may consist of zero or more \l QNdefRecord entries, which can be identified by their type.
+For more information about processing of records, see the \l QNdefRecord class documentation.
+As the above code demonstrates, writing of NDEF messages is triggered via
+\l QNearFieldTarget::writeNdefMessages(). The successful completion of the write operation
+is indicated by the emission of the \l QNearFieldTarget::ndefMessagesWritten() signal. Any
+type of error during read or write is indicated via \l QNearFieldTarget::error().
+
+\section2 Registering NDEF Message Handlers
+
+The above described method (of reading NDEF messages) directly connects to the platform's NFC infrastructure.
+However on some platforms (in particular mobile platforms) this may not actually trigger the target slot
+if the application is currently running in the background. This is not desirable in cases where an
+application wants to be activated if the platform detects a tag of particular type.
+For this purpose the Qt NFC API provides the possibility to register an NDEF message handler. The handler
+is called by the operating system, when the detected NDEF message matches the given filter criteria.
+Depending on the platform it may even be possible to start the application that registered the handler.
+
+\note This feature is not available on all platforms and, in addition to the code snippets below,
+may require further platform specific setup.
+
+\snippet annotatedurl/main.cpp QNearFieldManager register handler
+
+For comparison an application that uses an empty NDEF filter (match all behavior) in combination with
+\l QNearFieldManager::registerNdefMessageHandler() would behave similarly to another application that uses
+\l QNearFieldTarget::readNdefMessages() while being in the forground. For more information about
+registration details of NDEF message handlers, see the
+\l {QNearFieldManager#automatically-launching-ndef-message-handlers}{QNearFieldManager} class description.
+
+The content of \c handleMessage() may look like the snippet below. Any incoming NDEF message of type
+\c text or \c uri will be processed:
+
+\snippet annotatedurl/annotatedurl.cpp handleMessage 1
+\snippet annotatedurl/annotatedurl.cpp handleMessage 2
+\snippet annotatedurl/annotatedurl.cpp handleMessage 3
+\snippet annotatedurl/annotatedurl.cpp handleMessage 4
+
+\section2 Sharing Files and Messages
+
+Since Qt 5.3, Qt NFC provides a generic NFC share feature. If both devices support the same protocol,
+the feature can be used to share files or NDEF messages. The advantage is that the two involved partners
+can quickly establish a connection via NFC but transfer the data through, for example, Bluetooth or Wifi.
+Effectively, this combines the low configuration effort of NFC with high data rate communication bearers
+which usually require a much more complex setup.
+
+\note The API does not make any guarantees about the actual communication bearer used during the transfer.
+The bearer is chosen based on the device's capabilities and the properties of the to-be-shared data.
+
+\l QNearFieldShareManager and \l QNearFieldShareTarget are responsible for accessing the NFC share feature.
+
+\section1 QML Overview
+
+The QML API only supports a very small subset of the Qt NFC feature set. This section outlines the available QML features.
+
+\section2 Reading NDEF Messages
+
+The user can specify NDEF filters and use those filters to register for the automatic reception of NDEF
+messages which match those filters. The \l NearField::messageRecords property contains the list of NDEF records
+of the last NDEF message read matching the given filters.
+
+\snippet doc_src_qtnfc.qml QML register for messages
+
+If no filter is set, the message handler will match all incoming NDEF messages.
 */
diff --git a/src/nfc/qnearfieldsharemanager.cpp b/src/nfc/qnearfieldsharemanager.cpp
index b3e736b6..43b1634b 100644
--- a/src/nfc/qnearfieldsharemanager.cpp
+++ b/src/nfc/qnearfieldsharemanager.cpp
@@ -58,6 +58,7 @@ QT_BEGIN_NAMESPACE
 
     \ingroup connectivity-nfc
     \inmodule QtNfc
+    \since 5.3
 
     Applications can share NDEF data or file content using NFC technology by tapping two NFC-enabled devices
     together. The QNearFieldShareManager provides a high level entry point to access this functionality.
diff --git a/src/nfc/qnearfieldsharetarget.cpp b/src/nfc/qnearfieldsharetarget.cpp
index 9ac66c5c..606090b5 100644
--- a/src/nfc/qnearfieldsharetarget.cpp
+++ b/src/nfc/qnearfieldsharetarget.cpp
@@ -58,9 +58,12 @@ QT_BEGIN_NAMESPACE
 
     \ingroup connectivity-nfc
     \inmodule QtNfc
+    \since 5.3
 
     The QNearFieldShareTarget class can be used for sharing NDEF message or files to a remote
     NFC enabled device supporting the same protocol.
+
+    \sa QNearFieldShareManager
 */
 
 /*!
diff --git a/src/src.pro b/src/src.pro
index 7f37867e..e2ed3c88 100644
--- a/src/src.pro
+++ b/src/src.pro
@@ -7,6 +7,10 @@ bluetooth_doc_snippets.subdir = bluetooth/doc/snippets
 bluetooth_doc_snippets.depends = bluetooth
 SUBDIRS += bluetooth_doc_snippets
 
+nfc_doc_snippets.subdir = nfc/doc/snippets
+nfc_doc_snippets.depends = nfc
+SUBDIRS += nfc_doc_snippets
+
 qtHaveModule(quick) {
     imports.depends += bluetooth nfc
     SUBDIRS += imports