Wifi - c++/qml getting started guide and wifi doc update

c++ getting started guide
qml getting started guide
documenting qml elements
documenting c++ classes

Task-number: QTEE-810
Change-Id: I669d11c65e5359fc9ec863b03b8b56ce2ef1151b
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@theqtcompany.com>
Reviewed-by: Kalle Viironen <kalle.viironen@theqtcompany.com>

14 files changed, 606 insertions, 338 deletions

diff --git a/src/doc/config/b2qt.qdocconf b/src/doc/config/b2qt.qdocconf
index c5b4a9a..727930a 100644
--- a/src/doc/config/b2qt.qdocconf
+++ b/src/doc/config/b2qt.qdocconf
@@ -4,15 +4,18 @@ naturallanguage              = en_US
 outputencoding               = UTF-8
 sourceencoding               = UTF-8
 
-project                      = QtEnterpriseEmbedded
+project                      = QtForDeviceCreation
 description                  = Qt for Device Creation
 version                      = 4.0.0
 
 sourcedirs                   = ../src \
                                ../../imports/wifi \
-                               ../../imports/utils
+                               ../../imports/utils \
+                               ../../wifi
 
-headerdirs                   = ../../imports/wifi
+headerdirs                  += ../../wifi
+
+exampledirs +=                 ../../../examples
 
 imagedirs                   += ../images
 
@@ -43,4 +46,6 @@ macro.B2QA                   = "\\e {Boot to Qt for embedded Android}"
 macro.B2QL                   = "\\e {Boot to Qt for embedded Linux}"
 
 navigation.landingpage = "Qt for Device Creation"
-navigation.qmltypespage = "Add-On QML Types"
+navigation.qmltypespage = "Add-On Modules"
+
+Cpp.ignoreDirectives        += Q_DECLARE_LOGGING_CATEGORY
diff --git a/src/doc/src/qtee-changelog.qdoc b/src/doc/src/qtee-changelog.qdoc
index 5f18e4c..4113e52 100644
--- a/src/doc/src/qtee-changelog.qdoc
+++ b/src/doc/src/qtee-changelog.qdoc
@@ -179,7 +179,7 @@
         \li Update new content to device without erasing it first on \B2QL
         \li All images now contain generally used CA certificates
         \li Toolchains updated to support Qt WebEngine
-        \li Documentation was added for QML types provided by the \l {QtWifi Module}
+        \li Documentation was added for QML types provided by the \l {B2Qt.Wifi Module}
         \li Emulator: Debug logging functionality was added
         \li Various documentation improvements
         \li \SDK installer error handling was improved
diff --git a/src/doc/src/qtee-index.qdoc b/src/doc/src/qtee-index.qdoc
index 02eb4e2..41eff4b 100644
--- a/src/doc/src/qtee-index.qdoc
+++ b/src/doc/src/qtee-index.qdoc
@@ -68,7 +68,7 @@
     \section1 Reference Documentation
 
     \list
-        \li \l{Add-On QML Types}
+        \li \l{Add-On Modules}
     \endlist
 */
 
diff --git a/src/doc/src/qtee-licenses.qdoc b/src/doc/src/qtee-licenses.qdoc
index daf8b82..791ec92 100644
--- a/src/doc/src/qtee-licenses.qdoc
+++ b/src/doc/src/qtee-licenses.qdoc
@@ -21,7 +21,7 @@
     \page qtee-licenses.html
     \title License Information
     \previouspage qtee-troubleshooting.html
-    \nextpage qtee-qml-reference.html
+    \nextpage qtee-module-reference.html
 
     \section1 Licensing
 
diff --git a/src/doc/src/qtee-qml-reference.qdoc b/src/doc/src/qtee-qml-reference.qdoc
index 0107e97..121b534 100644
--- a/src/doc/src/qtee-qml-reference.qdoc
+++ b/src/doc/src/qtee-qml-reference.qdoc
@@ -18,14 +18,14 @@
 ****************************************************************************/
 
 /*!
-    \page qtee-qml-reference.html
-    \title Add-On QML Types
+    \page qtee-module-reference.html
+    \title Add-On Modules
     \previouspage qtee-licenses.html
 
-    The following QML modules are included in the \B2Q stack and provide
-    additional QML types that are useful in an embedded application:
+    The following modules included in the \B2Q stack, provide
+    additional API that are useful for an embedded application:
 
-    \annotatedlist qtee-qmlmodules
+    \annotatedlist qtee-modules
 
     \section1 B2Qt Utils Module
 
@@ -33,6 +33,12 @@
 
     \section1 B2Qt Wifi Module
 
+    \section2 QML Types
+
     \annotatedlist wifi-qmltypes
+
+    \section2 C++ Classes
+
+    \annotatedlist wifi-cppclasses
 */
 
diff --git a/src/imports/utils/plugin.cpp b/src/imports/utils/plugin.cpp
index 4012e96..a4f8810 100644
--- a/src/imports/utils/plugin.cpp
+++ b/src/imports/utils/plugin.cpp
@@ -21,9 +21,16 @@
 
 /*!
     \qmlmodule B2Qt.Utils 1.0
-    \title B2Qt Utils Module
+    \title B2Qt Utils QML Module
     \ingroup qtee-qmlmodules
     \brief A collection of utility functions, accessible from QML.
+*/
+
+/*!
+    \page b2qt-addon-utils.html
+    \title B2Qt Utils Module
+    \ingroup qtee-modules
+    \brief A collection of utility functions, accessible from QML.
 
     Provides various utility functions for controlling an embedded
     device, such as display brightness, IP address and hostname, and
@@ -41,6 +48,8 @@
           the platforms.
 
     \section1 QML Types
+
+    \annotatedlist utils-qmltypes
 */
 
 /*!
diff --git a/src/imports/wifi/pluginmain.cpp b/src/imports/wifi/pluginmain.cpp
index f706023..a778fa2 100644
--- a/src/imports/wifi/pluginmain.cpp
+++ b/src/imports/wifi/pluginmain.cpp
@@ -24,6 +24,304 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlmodule B2Qt.Wifi 1.0
+    \title B2Qt Wifi QML Module
+    \ingroup qtee-qmlmodules
+    \brief A module for managing wireless network connectivity.
+
+*/
+
+/*!
+    \page b2qt-addon-wifi.html
+    \title B2Qt Wifi Module
+    \ingroup qtee-modules
+    \brief A module for managing wireless network connectivity.
+
+    B2Qt.Wifi provides QML types and C++ classes for:
+
+    \list
+    \li Wifi backend handling
+    \li Retrieval of information from Wifi network access points
+    \li Wifi connection handling
+    \li System's network interface configuration
+    \li Other tasks that allow the device to access network
+    \endlist
+
+    \section1 Writing the Code
+
+    Depending on what fits best with the application, you can choose to use
+    either C++ or QML for accessing Wifi functionality. If the majority of the
+    user interface is written in QML, it is recommended that you use the QML
+    types, which provide a simpler and declarative way to handle Wifi networks.
+
+    \list
+    \li \l{Getting Started with B2Qt.Wifi in QML}
+    \li \l{Getting Started with B2Qt.Wifi in C++}
+    \endlist
+
+    \section1 API Reference
+
+    \section2 QML Types
+
+    \annotatedlist wifi-qmltypes
+
+    \section2 C++ Classes
+
+    \annotatedlist wifi-cppclasses
+*/
+
+/*!
+    \module B2Qt.Wifi.Cpp 1.0
+    \title B2Qt Wifi C++ Module
+    \ingroup qtee-cppmodules
+    \brief A module for managing wireless network connectivity.
+*/
+
+/*!
+    \qmltype WifiManager
+    \inqmlmodule B2Qt.Wifi
+    \ingroup wifi-qmltypes
+    \brief Main interface to the Wifi functionality.
+
+    WifiManager is a singleton type that is a central point for handling Wifi functionality
+    related tasks. You can use WifiManager's API to control the Wifi backend, scan surroundings for
+    Wifi access points and connect a device to a wireless network.
+
+    When scanning for networks, WifiManager packs the results in a list-based data model which can
+    be used with Qt's Model/View classes. Information about the Wifi networks is supplied via the model's
+    interface, accessed with the following roles:
+
+    \list
+    \li \e ssid - informal (human) name of a Wifi network
+    \li \e bssid - basic service set identification of a network, used to uniquely identify BSS
+    \li \e signalStrength - strength of a Wifi signal, measured in dBm
+    \li \e supportsWPA - holds whether network access point supports WPA security protocol
+    \li \e supportsWPA2 - holds whether network access point supports WPA2 security protocol
+    \li \e supportsWEP - holds whether network access point supports WEP security protocol
+    \li \e supportsWPS - holds whether network access point supports WPS security protocol
+    \endlist
+ */
+
+/*!
+    \qmlproperty enumeration WifiManager::NetworkState
+    \readonly
+
+    This property holds the current state of the network connection.
+
+    \list
+    \li \e WifiManager.Disconnected - Not connected to any network
+    \li \e WifiManager.Authenticating - Verifying password with the network provider
+    \li \e WifiManager.HandshakeFailed - Incorrect password provided
+    \li \e WifiManager.ObtainingIPAddress - Requesting IP address from DHCP server
+    \li \e WifiManager.DhcpRequestFailed - Could not retrieve IP address
+    \li \e WifiManager.Connected - Ready to process network requests
+    \endlist
+*/
+
+/*!
+    \qmlproperty enumeration WifiManager::BackendState
+    \readonly
+
+    This property holds the current state of the Wifi backend.
+
+    \list
+    \li \e WifiManager.Initializing - Wireless supplicant is starting up
+    \li \e WifiManager.Running - Supplicant is initialized and ready to process commands
+    \li \e WifiManager.Terminating - Shutting down wireless supplicant
+    \li \e WifiManager.NotRunning - Wireless supplicant process is not running
+    \endlist
+*/
+
+/*!
+    \qmlsignal WifiManager::networkStateChanged(NetworkState networkState)
+
+    This signal is emitted whenever changes in a network state occur. The network name for
+    which the NetworkState change events are send can be obtained from currentSSID.
+
+    \sa NetworkState, currentSSID
+*/
+
+/*!
+    \qmlsignal WifiManager::backendStateChanged(BackendState backendState)
+
+    This signal is emitted whenever changes in a backend state occur.
+
+    \sa start, stop
+*/
+
+/*!
+    \qmlsignal WifiManager::currentSSIDChanged(string currentSSID)
+
+    This signal is emitted when switching between different Wifi networks.
+
+    \sa start, stop
+*/
+
+/*!
+    \qmlsignal WifiManager::scanningChanged(bool scanning)
+
+    This signal is emitted when device starts or stops to scan for available Wifi networks.
+
+    \sa scanning
+*/
+
+/*!
+    \qmlsignal WifiManager::lastErrorChanged(string error)
+
+    This signal is emitted if some internal process has failed, \a error contains
+    a message on what has failed.
+
+    \sa connect
+*/
+
+/*!
+    \qmlproperty model WifiManager::networks
+    \readonly
+
+    This property holds a list-based data model of networks that can be sensed by a device.
+    Model can be used with Qt's Model/View classes like ListView. Data in the model is updated
+    every 5 seconds if scanning is enabled.
+
+    \sa scanning
+*/
+
+/*!
+    \qmlproperty string WifiManager::currentSSID
+    \readonly
+
+    This property holds a network name of last selected network, the network for
+    which the NetworkState change events are sent. Property can contain an empty
+    string when no active network connection exists.
+*/
+
+/*!
+    \qmlmethod WifiManager::start()
+
+    Start the Wifi backend. This function returns immediately, the BackendState
+    change events are delivered asynchronously.
+
+    \sa stop, BackendState
+*/
+
+/*!
+    \qmlmethod WifiManager::stop()
+
+    Stop the Wifi backend and if connected to any network shut down the network connection.
+    This function returns immediately, the BackendState change events are delivered asynchronously.
+
+    \sa start, BackendState
+*/
+
+/*!
+    \qmlproperty bool WifiManager::scanning
+
+    This property holds whether or not the backend is scanning for Wifi networks. To
+    preserve battery energy, set this property to false when scanning is not required.
+    When enabled, new readings are taken every 5 seconds.
+
+    For scanning to work, first you need to initialize the Wifi backend.
+
+    \sa start
+*/
+
+/*!
+    \qmlproperty string WifiManager::lastError
+    \readonly
+
+    This property holds an error message if some internal process has failed.
+
+    \sa connect
+*/
+
+/*!
+    \qmlmethod bool WifiManager::connect(WifiConfiguration config)
+
+    Connect a device to a network using the \a config network configuration.
+    This method returns \a true if the network with provoded configuration could be
+    successfully added by the backend or \a false on failure, to obtain an error message
+    read lastError property.
+
+    \sa disconnect, NetworkState, lastError
+*/
+
+/*!
+    \qmlmethod WifiManager::disconnect()
+
+    Disconnect from currently connected network connection.
+
+    \sa connect, NetworkState
+*/
+
+/*!
+    \qmltype WifiDevice
+    \inqmlmodule B2Qt.Wifi
+    \ingroup wifi-qmltypes
+    \brief Represents a physical device.
+
+    Use this element to query if a device is Wifi capable, before attempting
+    to use the functionality of WifiManager.
+
+    \qml
+    import B2Qt.Wifi 1.0
+
+    GroupBox {
+        id: wifiOptions
+        title: "Wifi"
+        visible: false
+
+        Component.onCompleted: {
+            if (WifiDevice.wifiSupported()) {
+                var component = Qt.createComponent("WifiGroupBoxContent.qml")
+                var wifi = component.createObject(wifiOptions.contentItem)
+                if (wifi)
+                    wifiOptions.visible = true
+            } else {
+                print("Wifi functionality not available on this device.")
+            }
+        }
+    }
+    \endqml
+*/
+
+/*!
+    \qmlmethod bool WifiDevice::wifiSupported()
+
+    Returns \a true if a device is Wifi capable - Wifi driver and firmware has been
+    successfully loaded by the system, otherwise returns \a false.
+*/
+
+/*!
+    \qmltype WifiConfiguration
+    \inqmlmodule B2Qt.Wifi
+    \ingroup wifi-qmltypes
+    \brief Used to define a network configuration.
+
+    WifiConfiguration object represents a single network configuration. Use this object
+    to configure a properties of your network, for example what passphrase and security
+    protocol to use. WifiManager's connect() function takes this object and connects a
+    device to a network that matches the provided configuration.
+*/
+
+/*!
+    \qmlproperty string WifiConfiguration::ssid
+
+    This property holds informal (human) name of a Wifi network.
+*/
+
+/*!
+    \qmlproperty string WifiConfiguration::passphrase
+
+    This property holds the passphrase to use for authenticating with a network.
+*/
+
+/*!
+    \qmlproperty string WifiConfiguration::protocol
+
+    This property holds the security protocols to use for Wifi connection.
+    WPA is used by default if property is not set, supported values are: WPA, WPA2, WEP, WPS.
+*/
+
 static QObject *globalWifiDevice(QQmlEngine *, QJSEngine *)
 {
     return new QWifiDevice;
diff --git a/src/wifi/qwificonfiguration.cpp b/src/wifi/qwificonfiguration.cpp
index f2c859a..87ef440 100644
--- a/src/wifi/qwificonfiguration.cpp
+++ b/src/wifi/qwificonfiguration.cpp
@@ -38,6 +38,18 @@ QWifiConfigurationPrivate::QWifiConfigurationPrivate(QWifiConfiguration *config)
 {
 }
 
+/*!
+    \class QWifiConfiguration
+    \inmodule B2Qt.Wifi.Cpp
+    \ingroup wifi-cppclasses
+    \brief Used to define a network configuration.
+
+    QWifiConfiguration object represents a single network configuration. Use it
+    to configure properties of your network. For example, passphrase, security
+    protocol to use, and so on. QWifiManager::connect() function uses this
+    information to find a network that matches the provided configuration, before
+    establishing a connection.
+ */
 
 QWifiConfiguration::QWifiConfiguration(QObject *parent)
     : QObject(parent)
@@ -50,40 +62,55 @@ QWifiConfiguration::~QWifiConfiguration()
     delete d_ptr;
 }
 
-void QWifiConfiguration::setSsid(const QString &ssid)
-{
-    Q_D(QWifiConfiguration);
-    d->m_ssid = ssid;
-}
-
+/*!
+    \property QWifiConfiguration::ssid
+    \brief a human-readable name of a Wifi network
+*/
 QString QWifiConfiguration::ssid() const
 {
     Q_D(const QWifiConfiguration);
     return d->m_ssid;
 }
 
-void QWifiConfiguration::setPassphrase(const QString &psk)
+void QWifiConfiguration::setSsid(const QString &ssid)
 {
     Q_D(QWifiConfiguration);
-    d->m_psk = psk;
+    d->m_ssid = ssid;
 }
 
+/*!
+    \property QWifiConfiguration::passphrase
+    \brief a passphrase to use for authenticating access to a network
+*/
 QString QWifiConfiguration::passphrase() const
 {
     Q_D(const QWifiConfiguration);
     return d->m_psk;
 }
 
-void QWifiConfiguration::setProtocol(const QString &protocol)
+void QWifiConfiguration::setPassphrase(const QString &passphrase)
 {
     Q_D(QWifiConfiguration);
-    d->m_protocol = protocol;
+    d->m_psk = passphrase;
 }
 
+/*!
+    \property QWifiConfiguration::protocol
+    \brief a security protocol to use for Wifi connection
+
+    WPA is used by default if protocol is not explicitly set.
+    Supported values are: WPA, WPA2, WEP, WPS.
+*/
 QString QWifiConfiguration::protocol() const
 {
     Q_D(const QWifiConfiguration);
     return d->m_protocol;
 }
 
+void QWifiConfiguration::setProtocol(const QString &protocol)
+{
+    Q_D(QWifiConfiguration);
+    d->m_protocol = protocol;
+}
+
 QT_END_NAMESPACE
diff --git a/src/wifi/qwificonfiguration.h b/src/wifi/qwificonfiguration.h
index 2253fbb..9b03c9e 100644
--- a/src/wifi/qwificonfiguration.h
+++ b/src/wifi/qwificonfiguration.h
@@ -38,7 +38,7 @@ public:
 
     void setSsid(const QString &ssid);
     QString ssid() const;
-    void setPassphrase(const QString &psk);
+    void setPassphrase(const QString &passphrase);
     QString passphrase() const;
     void setProtocol(const QString &protocol);
     QString protocol() const;
diff --git a/src/wifi/qwifidevice.cpp b/src/wifi/qwifidevice.cpp
index 4f100c4..f3eb62b 100644
--- a/src/wifi/qwifidevice.cpp
+++ b/src/wifi/qwifidevice.cpp
@@ -28,44 +28,25 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-    \qmltype WifiDevice
-    \inqmlmodule QtWifi
-    \ingroup wifi-qmltypes
-    \brief Represents a physical device
-
-    Use this element to query if a device is WiFi capable before attempting
-    to use functionality of WifiManager.
-
-    \qml
-    import QtWifi 1.0
-
-    GroupBox {
-        id: wifiOptions
-        title: "Wifi"
-        visible: false
-
-        Component.onCompleted: {
-            if (WifiDevice.wifiSupported()) {
-                var component = Qt.createComponent("WifiGroupBox.qml")
-                var wifi = component.createObject(wifiOptions.contentItem)
-                if (wifi)
-                    wifiOptions.visible = true
-            } else {
-                print("WiFi functionality not available on this device.")
-            }
-        }
+    \class QWifiDevice
+    \inmodule B2Qt.Wifi.Cpp
+    \ingroup wifi-cppclasses
+    \brief Represents a physical device.
+
+    Use this class to query if a device is Wifi capable, before attempting
+    to use the functionality of QWifiManager.
+
+    \code
+    QWifiManager *m_wifiManager = 0;
+    if (QWifiDevice::wifiSupported())
+        m_wifiManager = QWifiManager::instance();
+
+    if (m_wifiManager) {
+        m_wifiManager->start();
+        // and other wifi related code
     }
-    \endqml
-*/
-
-/*!
-    \qmlmethod bool QWifiDevice::wifiSupported()
-
-    Returns true if the device is WiFi capable - WiFi driver and firmware has been
-    successfully loaded by the system, otherwise returns false.
-
-    \sa wifiInterfaceName
-*/
+    \endcode
+ */
 
 QWifiDevice::QWifiDevice()
 {
@@ -75,6 +56,10 @@ QWifiDevice::~QWifiDevice()
 {
 }
 
+/*!
+    Returns \a true if a device is Wifi capable - Wifi driver and firmware has been
+    successfully loaded by the system, otherwise returns \a false.
+*/
 bool QWifiDevice::wifiSupported()
 {
 #ifdef Q_OS_ANDROID_NO_SDK
@@ -108,18 +93,15 @@ bool QWifiDevice::wifiSupported()
 }
 
 /*!
-    \fn QByteArray QWifiDevice::wifiInterfaceName()
-
-    Returns WiFi interface name.
+    Returns Wifi interface name.
 
-    \note On Android WiFi interface name is read from "wifi.interface" system property.
-    On Linux WiFi interface name is read from B2QT_WIFI_INTERFACE environmental variable if
-    it is set. The default interface name is "wlan0" if reading the designated places does not
-    provide an interface name.
-
-    /sa setWifiInterfaceName
-*/
+    \note On Android, the Wifi interface name is read from "wifi.interface"
+    system property. On Linux, it is read from the \c B2QT_WIFI_INTERFACE
+    environment variable if it is set, otherwise, the default interface
+    name ("\e{wlan0}") is used.
 
+    \sa setWifiInterfaceName()
+ */
 QByteArray QWifiDevice::wifiInterfaceName()
 {
     QByteArray ifc;
@@ -135,11 +117,10 @@ QByteArray QWifiDevice::wifiInterfaceName()
 }
 
 /*!
-    \fn void QWifiDevice::setWifiInterfaceName(const QByteArray &name)
-
-    A conveniece method for settings WiFi interface name.
-*/
+    A conveniece method to set the Wifi interface name.
 
+    \sa wifiInterfaceName()
+ */
 void QWifiDevice::setWifiInterfaceName(const QByteArray &name)
 {
 #ifdef Q_OS_ANDROID_NO_SDK
diff --git a/src/wifi/qwifimanager.cpp b/src/wifi/qwifimanager.cpp
index de35224..db188bf 100644
--- a/src/wifi/qwifimanager.cpp
+++ b/src/wifi/qwifimanager.cpp
@@ -27,73 +27,6 @@
 
 QT_BEGIN_NAMESPACE
 
-/*!
-    \qmlmodule QtWifi 1.0
-    \title QtWifi Module
-    \ingroup qtee-qmlmodules
-    \brief A module for managing wireless network connectivity.
-
-    Provides QML types for controlling WiFi networks - handling WiFi backend initialization,
-    retrieving information from nearby WiFi access points, setting up and bringing down WiFi
-    connections, querying DHCP server for IP address.
-
-    The import command for adding these QML types is:
-
-    \code
-    import QtWifi 1.0
-    \endcode
-
-    \section1 API Reference
-*/
-
-/*!
-
-    \qmltype WifiManager
-    \inqmlmodule QtWifi
-    \ingroup wifi-qmltypes
-    \brief Main interface to the WiFi functionality.
-
-    WifiManager is a singleton type that provides information about the WiFi backend and
-    available networks, use it to control the WiFi backend, scan for wireless networks
-    and connect to selected network. WifiManager provides events for backend and network
-    state changes.
-
- */
-
-/*!
-    \qmlsignal void WifiManager::networkStateChanged(NetworkState networkState)
-
-    This signal is emitted whenever changes in a network state occur. The network name for
-    which the state changes events are send can be obtained from currentSSID.
-
-    \sa networkState
-*/
-
-/*!
-    \qmlsignal void WifiManager::backendStateChanged(BackendState backendState)
-
-    This signal is emitted whenever changes in a backend state occur.
-
-    \sa start, stop
-*/
-
-/*!
-    \qmlsignal void WifiManager::currentSSIDChanged(string currentSSID)
-
-    This signal is emitted when switching between different WiFi networks.
-
-    \sa start, stop
-*/
-
-/*!
-    \qmlsignal void WifiManager::scanningChanged(bool scanning)
-
-    This signal is emitted when device starts or stops to scan for available wifi networks.
-
-    \sa scanning
-
-*/
-
 // must be in the same order as in enum {} definiton
 const char *nsText[] = { "Disconnected", "Authenticating", "HandshakeFailed",
                          "ObtainingIPAddress", "DhcpRequestFailed", "Connected" };
@@ -259,8 +192,105 @@ void QWifiManagerPrivate::updateLastError(const QString &error)
     emit q->lastErrorChanged(m_lastError);
 }
 
+/*!
+    \class QWifiManager
+    \inmodule B2Qt.Wifi.Cpp
+    \ingroup wifi-cppclasses
+    \brief Enables an application to be Wifi-capable.
+
+    QWifiManager is a singleton class that handles Wifi-related tasks. You can
+    use QWifiManager to control the Wifi backend, scan for Wifi access points,
+    and connect to a wireless network.
+
+    QWifiManager packs the scan results in a list-based data model, which can
+    be used with Qt's Model/View classes. Information about a Wifi network can
+    be accessed using the QWifiManager::Roles data roles.
+ */
+
+/*!
+    \enum QWifiManager::NetworkState
+
+    Describes current state of the network connection.
+
+    \value Disconnected Not connected to any network
+    \value Authenticating Verifying password with the network provider
+    \value HandshakeFailed Incorrect password provided
+    \value ObtainingIPAddress Requesting IP address from DHCP server
+    \value DhcpRequestFailed Could not retrieve IP address
+    \value Connected Ready to process network requests
+ */
+
+/*!
+    \enum QWifiManager::BackendState
+
+    Describes current state of the Wifi backend.
+
+    \value Initializing Wireless supplicant is starting up
+    \value Running Supplicant is initialized and ready to process commands
+    \value Terminating Shutting down wireless supplicant
+    \value NotRunning Wireless supplicant process is not running
+ */
+
+/*!
+    \enum QWifiManager::Roles
+
+    Data roles supported by the data model returned from QWifiManager::networks()
+
+    \value SSID informal (human) name of a Wifi network (QString)
+    \value BSSID basic service set identification of a network, used to uniquely identify BSS (QString)
+    \value SignalStrength strength of a Wifi signal, measured in dBm (int)
+    \value WPASupported holds whether network access point supports WPA security protocol (QString)
+    \value WPA2Supported holds whether network access point supports WPA2 security protocol (QString)
+    \value WEPSupported holds whether network access point supports WEP security protocol (QString)
+    \value WPSSupported holds whether network access point supports WPS security protocol (QString)
+ */
+
+/*!
+    \fn QWifiManager::networkStateChanged(NetworkState networkState)
+
+    This signal is emitted whenever the network state changes. The network name
+    for which the signal is emitted, can be obtained from currentSSID.
+
+    \sa NetworkState, currentSSID()
+ */
+
+/*!
+    \fn QWifiManager::backendStateChanged(BackendState backendState)
+
+    This signal is emitted whenever the backend state changes.
+
+    \sa start(), stop()
+ */
+
+/*!
+    \fn QWifiManager::currentSSIDChanged(string currentSSID)
+
+    This signal is emitted when switching between different Wifi networks.
+
+    \sa start(), stop()
+ */
+
+/*!
+    \fn QWifiManager::scanningChanged(bool scanning)
+
+    This signal is emitted when device starts or stops to scan for available Wifi networks.
+
+    \sa isScanning()
+ */
+
+/*!
+    \fn QWifiManager::lastErrorChanged(const string error)
+
+    This signal is emitted if some internal process has failed, \a error contains
+    a message on what has failed.
+
+    \sa connect()
+ */
 
 QWifiManager* QWifiManager::m_instance = 0;
+/*!
+    Returns a singleton instance of QWifiManager.
+*/
 QWifiManager* QWifiManager::instance()
 {
     if (!m_instance)
@@ -287,6 +317,9 @@ QWifiManager::QWifiManager()
     d->updateWifiState();
 }
 
+/*!
+    Destroys the QWifiManager singleton instance.
+ */
 QWifiManager::~QWifiManager()
 {
     Q_D(QWifiManager);
@@ -296,17 +329,15 @@ QWifiManager::~QWifiManager()
 }
 
 /*!
-    \qmlproperty WifiNetworkListModel WifiManager::networks
-    \readonly
+    \property QWifiManager::networks
+    \brief a list-based data model of networks
 
-    This property holds a list of networks that can be sensed by a device. Use the returned
-    model as data model in ListView, model is updated every 5 seconds.
-
-    WifiNetworkListModel is a simple data model consisting of WifiNetwork objects, accessed with
-    the "network" data role name. Instances of WifiNetwork cannot be created directly from the QML system.
+    Returns a list-based data model of networks that can be sensed by a device.
+    Model can be used with Qt's Model/View classes such as QListView. Data in
+    the model is updated every 5 seconds if scanning is enabled.
 
+    \sa isScanning()
 */
-
 QAbstractListModel *QWifiManager::networks() const
 {
     Q_D(const QWifiManager);
@@ -314,13 +345,13 @@ QAbstractListModel *QWifiManager::networks() const
 }
 
 /*!
-    \qmlproperty string WifiManager::currentSSID
-    \readonly
+    \property QWifiManager::currentSSID
+    \brief a network name of the last selected network
 
-    This property holds the network name for which the networkState changes events are sent or
-    or an empty string when there is no active network.
+    The network for which the NetworkState change signals are emitted.
+    Property can contain an empty string when there is no active network
+    connection.
 */
-
 QString QWifiManager::currentSSID() const
 {
     Q_D(const QWifiManager);
@@ -328,21 +359,11 @@ QString QWifiManager::currentSSID() const
 }
 
 /*!
-    \qmlproperty enumeration WifiManager::networkState
-    \readonly
-
-    This property holds the current state of the network connection.
-
-    \list
-    \li \e WifiManager.Disconnected - Not connected to any network
-    \li \e WifiManager.Authenticating - Verifying password with the network provider
-    \li \e WifiManager.HandshakeFailed - Incorrect password provided
-    \li \e WifiManager.ObtainingIPAddress - Requesting IP address from DHCP server
-    \li \e WifiManager.DhcpRequestFailed - Could not retrieve IP address
-    \li \e WifiManager.Connected - Ready to process network requests
-    \endlist
-*/
+    \property QWifiManager::networkState
+    \brief the current network state
 
+    Returns the current network state.
+*/
 QWifiManager::NetworkState QWifiManager::networkState() const
 {
     Q_D(const QWifiManager);
@@ -350,19 +371,11 @@ QWifiManager::NetworkState QWifiManager::networkState() const
 }
 
 /*!
-    \qmlproperty enumeration WifiManager::backendState
-    \readonly
+    \property QWifiManager::backendState
+    \brief the current backend state.
 
-    This property holds the current state of the WiFi backend.
-
-    \list
-    \li \e WifiManager.Initializing - Wireless supplicant is starting up
-    \li \e WifiManager.Running - Supplicant is initialized and ready to process commands
-    \li \e WifiManager.Terminating - Shutting down wireless supplicant
-    \li \e WifiManager.NotRunning - Wireless supplicant process is not running
-    \endlist
+    Returns the current backend state.
 */
-
 QWifiManager::BackendState QWifiManager::backendState() const
 {
     Q_D(const QWifiManager);
@@ -370,14 +383,11 @@ QWifiManager::BackendState QWifiManager::backendState() const
 }
 
 /*!
-    \qmlmethod void WifiManager::start()
-
-    Start the WiFi backend. This function returns immediately, the backendState
+    Start the Wifi backend. This function returns immediately, the BackendState
     change events are delivered asynchronously.
 
-    \sa stop, backendState
- */
-
+    \sa stop(), BackendState
+*/
 void QWifiManager::start()
 {
     Q_D(QWifiManager);
@@ -385,47 +395,35 @@ void QWifiManager::start()
 }
 
 /*!
-    \qmlmethod void WifiManager::stop()
-
-    Stop the WiFi backend and if connected to any network shut down network connection.
-    This function returns immediately, the backendState change events are delivered asynchronously.
-
-    \sa start, backendState
- */
+    Stop the Wifi backend. Closes the open network connection if any.
+    This function returns immediately, and the BackendState change events are
+    delivered asynchronously.
 
+    \sa start(), BackendState
+*/
 void QWifiManager::stop()
 {
     Q_D(QWifiManager);
     d->m_wifiController->call(QWifiController::TerminateBackend);
 }
 
-void QWifiManager::handleBackendStateChanged(BackendState backendState)
-{
-    Q_D(QWifiManager);
-    switch (backendState) {
-    case Running:
-        d->m_setCurrentSSID = true;
-        break;
-    case NotRunning:
-        d->updateNetworkState(Disconnected);
-        break;
-    default:
-        break;
-    }
-    d->updateBackendState(backendState);
-}
+/*!
+    \property QWifiManager::scanning
+    \brief whether the backend is scanning for Wifi networks.
 
-void QWifiManager::handleDhcpRequestFinished(const QString &status)
+    Sets whether to scan the environment for Wifi access points.
+
+    To preserve battery energy, set this property to false when scanning is not required.
+    When enabled, new readings are taken every 5 seconds.
+
+    \note You must initialize the Wifi backend to scan for networks.
+
+    \sa start()
+*/
+bool QWifiManager::isScanning() const
 {
-    Q_D(QWifiManager);
-    qCDebug(B2QT_WIFI) << "handleDhcpRequestFinished: " << status << " for " << d->m_currentSSID;
-    if (status == QLatin1String("success")) {
-        d->emitCurrentSSIDChanged();
-        d->updateNetworkState(Connected);
-        d->call(QStringLiteral("SAVE_CONFIG"));
-    } else {
-        d->updateNetworkState(DhcpRequestFailed);
-    }
+    Q_D(const QWifiManager);
+    return d->m_scanning;
 }
 
 void QWifiManager::setScanning(bool scanning)
@@ -446,22 +444,14 @@ void QWifiManager::setScanning(bool scanning)
 }
 
 /*!
-    \qmlproperty bool WifiManager::scanning
-
-    This property holds whether or not the backend is scanning for WiFi networks. To
-    preserve battery energy, set this property to false when scanning is not required.
+    \property QWifiManager::lastError
+    \brief a QString containing the last error message set by QWifiManager.
 
-    Before starting to scan for networks, you need to initialize the WiFi backend.
+    Returns a QString containing the last error message set by QWifiManager.
+    This helps in diagnosing the internal process failures.
 
-    \sa start
+    \sa connect()
 */
-
-bool QWifiManager::scanning() const
-{
-    Q_D(const QWifiManager);
-    return d->m_scanning;
-}
-
 QString QWifiManager::lastError() const
 {
     Q_D(const QWifiManager);
@@ -502,15 +492,14 @@ bool QWifiManager::event(QEvent *event)
     return QObject::event(event);
 }
 
-
 /*!
-    \qmlmethod void WifiManager::connect(WifiNetwork network, string passphrase)
-
-    Connect to network \a network and use passphrase \a passphrase for authentication.
-
-    \sa disconnect, networkState
- */
+    Connect a device to a network using the \a config network configuration.
+    This method returns \c true if the network with the provided configuration
+    could be successfully added by the backend or \c false on failure.
+    Use lastError() to obtain the error message on failure.
 
+    \sa disconnect(), NetworkState, lastError()
+*/
 bool QWifiManager::connect(QWifiConfiguration *config)
 {
     Q_D(QWifiManager);
@@ -583,13 +572,10 @@ bool QWifiManager::connect(QWifiConfiguration *config)
 }
 
 /*!
-    \qmlmethod void WifiManager::disconnect()
-
     Disconnect from currently connected network connection.
 
-    \sa connect, networkState
+    \sa connect(), networkState()
 */
-
 void QWifiManager::disconnect()
 {
     Q_D(QWifiManager);
@@ -597,4 +583,33 @@ void QWifiManager::disconnect()
     d->m_wifiController->call(QWifiController::StopDhcp);
 }
 
+void QWifiManager::handleBackendStateChanged(BackendState backendState)
+{
+    Q_D(QWifiManager);
+    switch (backendState) {
+    case Running:
+        d->m_setCurrentSSID = true;
+        break;
+    case NotRunning:
+        d->updateNetworkState(Disconnected);
+        break;
+    default:
+        break;
+    }
+    d->updateBackendState(backendState);
+}
+
+void QWifiManager::handleDhcpRequestFinished(const QString &status)
+{
+    Q_D(QWifiManager);
+    qCDebug(B2QT_WIFI) << "handleDhcpRequestFinished: " << status << " for " << d->m_currentSSID;
+    if (status == QLatin1String("success")) {
+        d->emitCurrentSSIDChanged();
+        d->updateNetworkState(Connected);
+        d->call(QStringLiteral("SAVE_CONFIG"));
+    } else {
+        d->updateNetworkState(DhcpRequestFailed);
+    }
+}
+
 QT_END_NAMESPACE
diff --git a/src/wifi/qwifimanager.h b/src/wifi/qwifimanager.h
index cd55f4d..7fc658c 100644
--- a/src/wifi/qwifimanager.h
+++ b/src/wifi/qwifimanager.h
@@ -42,7 +42,7 @@ class Q_DECL_EXPORT QWifiManager : public QObject
     Q_ENUMS(BackendState)
     Q_PROPERTY(NetworkState networkState READ networkState NOTIFY networkStateChanged)
     Q_PROPERTY(BackendState backendState READ backendState NOTIFY backendStateChanged)
-    Q_PROPERTY(bool scanning READ scanning WRITE setScanning NOTIFY scanningChanged)
+    Q_PROPERTY(bool scanning READ isScanning WRITE setScanning NOTIFY scanningChanged)
     Q_PROPERTY(QString currentSSID READ currentSSID NOTIFY currentSSIDChanged)
     Q_PROPERTY(QString lastError READ lastError NOTIFY lastErrorChanged)
     Q_PROPERTY(QAbstractListModel *networks READ networks CONSTANT)
@@ -64,13 +64,13 @@ public:
     };
 
     enum Roles {
-        SSIDRole = Qt::UserRole + 1,
-        BSSIDRole = Qt::UserRole + 2,
-        SignalRole = Qt::UserRole + 3,
-        WPARole = Qt::UserRole + 4,
-        WPA2Role = Qt::UserRole + 5,
-        WEPRole = Qt::UserRole + 6,
-        WPSRole = Qt::UserRole + 7
+        SSID           = Qt::UserRole + 1,
+        BSSID          = Qt::UserRole + 2,
+        SignalStrength = Qt::UserRole + 3,
+        WPASupported   = Qt::UserRole + 4,
+        WPA2Supported  = Qt::UserRole + 5,
+        WEPSupported   = Qt::UserRole + 6,
+        WPSSupported   = Qt::UserRole + 7
     };
 
     static QWifiManager *instance();
@@ -78,7 +78,7 @@ public:
 
     QAbstractListModel *networks() const;
     QString currentSSID() const;
-    bool scanning() const;
+    bool isScanning() const;
     void setScanning(bool scanning);
     NetworkState networkState() const;
     BackendState backendState() const;
diff --git a/src/wifi/qwifinetwork.cpp b/src/wifi/qwifinetwork.cpp
index 937cbfc..eb2b669 100644
--- a/src/wifi/qwifinetwork.cpp
+++ b/src/wifi/qwifinetwork.cpp
@@ -20,79 +20,6 @@
 
 QT_BEGIN_NAMESPACE
 
-/*!
-    \qmltype WifiNetwork
-    \inqmlmodule QtWifi
-    \ingroup wifi-qmltypes
-    \brief Represents a single WiFi network access point.
-
-    WifiNetwork provides a various information about WiFi network, like network
-    name, siganl strength and supported security protocols. Instances of WifiNetwork cannot
-    be created directly from the QML system, see WifiManager::networks.
-*/
-
-/*!
-    \qmlproperty string WifiNetwork::bssid
-    \readonly
-
-    This property holds basic service set identification of a network, used to uniquely
-    identify BSS.
-
-*/
-
-/*!
-    \qmlproperty string WifiNetwork::ssid
-    \readonly
-
-    This property holds a network name. The SSID is the informal (human) name of BSS.
-*/
-
-/*!
-    \qmlproperty int WifiNetwork::signalStrength
-    \readonly
-
-    This property holds the current strength of a WiFi signal, measured in dBm. New readings are
-    taken every 5 seconds.
-
-    \sa signalStrengthChanged
-*/
-
-/*!
-    \qmlproperty bool WifiNetwork::supportsWPA
-    \readonly
-
-    This property holds whether network access point supports WPA security protocol.
-*/
-
-/*!
-    \qmlproperty bool WifiNetwork::supportsWPA2
-    \readonly
-
-    This property holds whether network access point supports WPA2 security protocol.
-*/
-
-/*!
-    \qmlproperty bool WifiNetwork::supportsWEP
-    \readonly
-
-    This property holds whether network access point supports WEP security protocol.
-*/
-
-/*!
-    \qmlproperty bool WifiNetwork::supportsWPS
-    \readonly
-
-    This property holds whether network access point supports WPS security protocol.
-*/
-
-/*!
-    \qmlsignal void WifiNetwork::signalStrengthChanged(int strength)
-
-    This signal is emitted whenever signal strength has changed comparing the the
-    previous reading, the new signal's strength is \a strength.
-
-*/
-
 QWifiNetwork::QWifiNetwork(QObject *parent)
     : QObject(parent)
     , m_isOutOfRange(false)
diff --git a/src/wifi/qwifinetworklistmodel.cpp b/src/wifi/qwifinetworklistmodel.cpp
index 7a5de2a..6f53295 100644
--- a/src/wifi/qwifinetworklistmodel.cpp
+++ b/src/wifi/qwifinetworklistmodel.cpp
@@ -43,13 +43,13 @@ QWifiNetworkListModel::~QWifiNetworkListModel()
 QHash<int, QByteArray> QWifiNetworkListModel::roleNames() const
 {
     QHash<int, QByteArray> names;
-    names.insert(QWifiManager::SSIDRole, "ssid");
-    names.insert(QWifiManager::BSSIDRole, "bssid");
-    names.insert(QWifiManager::SignalRole, "signalStrength");
-    names.insert(QWifiManager::WPARole, "supportsWPA");
-    names.insert(QWifiManager::WPA2Role, "supportsWPA2");
-    names.insert(QWifiManager::WEPRole, "supportsWEP");
-    names.insert(QWifiManager::WPSRole, "supportsWPS");
+    names.insert(QWifiManager::SSID, "ssid");
+    names.insert(QWifiManager::BSSID, "bssid");
+    names.insert(QWifiManager::SignalStrength, "signalStrength");
+    names.insert(QWifiManager::WPASupported, "supportsWPA");
+    names.insert(QWifiManager::WPA2Supported, "supportsWPA2");
+    names.insert(QWifiManager::WEPSupported, "supportsWEP");
+    names.insert(QWifiManager::WPSSupported, "supportsWPS");
     return names;
 }
 
@@ -58,25 +58,25 @@ QVariant QWifiNetworkListModel::data(const QModelIndex &index, int role) const
     QWifiNetwork *n = m_networks.at(index.row());
 
     switch (role) {
-    case QWifiManager::SSIDRole:
+    case QWifiManager::SSID:
         return n->ssid();
         break;
-    case QWifiManager::BSSIDRole:
+    case QWifiManager::BSSID:
         return n->bssid();
         break;
-    case QWifiManager::SignalRole:
+    case QWifiManager::SignalStrength:
         return n->signalStrength();
         break;
-    case QWifiManager::WPARole:
+    case QWifiManager::WPASupported:
         return n->supportsWPA();
         break;
-    case QWifiManager::WPA2Role:
+    case QWifiManager::WPA2Supported:
         return n->supportsWPA2();
         break;
-    case QWifiManager::WEPRole:
+    case QWifiManager::WEPSupported:
         return n->supportsWEP();
         break;
-    case QWifiManager::WPSRole:
+    case QWifiManager::WPSSupported:
         return n->supportsWPS();
         break;
     default: