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>

6 files changed, 134 insertions, 61 deletions

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.
 */