Refine doc generation

Change-Id: I9da90086c63b88a5664f241da2fa9687c3882ddf
Reviewed-by: Kurt Pattyn <pattyn.kurt@gmail.com>

10 files changed, 232 insertions, 47 deletions

diff --git a/src/websockets/doc/qtwebsockets.qdocconfig b/src/websockets/doc/qtwebsockets.qdocconfig
new file mode 100644
index 0000000..0e57238
--- /dev/null
+++ b/src/websockets/doc/qtwebsockets.qdocconfig
@@ -0,0 +1,43 @@
+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+
+project                                             = QtWebSockets
+description                                         = Qt WebSockets Reference Documentation
+url                                                 = http://qt-project.org/doc/qt-$QT_VER/qtwebsockets
+version                                             = $QT_VERSION
+
+examplesinstallpath                                 = websockets
+
+qhp.projects                                        = QtWebSockets
+
+qhp.QtWebSockets.file                               = qtwebsockets.qhp
+qhp.QtWebSockets.namespace                          = org.qt-project.qtwebsockets.$QT_VERSION_TAG
+qhp.QtWebSockets.virtualFolder                      = qtwebsockets
+qhp.QtWebSockets.indexTitle                         = Qt WebSockets
+qhp.QtWebSockets.indexRoot                          =
+
+qhp.QtWebSockets.filterAttributes                   = qtwebsockets $QT_VERSION qtrefdoc
+qhp.QtWebSockets.customFilters.Qt.name              = QtWebSockets $QT_VERSION
+qhp.QtWebSockets.customFilters.Qt.filterAttributes  = qtwebsockets $QT_VERSION
+
+qhp.QtWebSockets.subprojects                        = classes
+qhp.QtWebSockets.subprojects.classes.title          = C++ Classes
+qhp.QtWebSockets.subprojects.classes.indexTitle     = Qt WebSockets C++ Classes
+qhp.QtWebSockets.subprojects.classes.selectors      = class fake:headerfile
+qhp.QtWebSockets.subprojects.classes.sortPages      = true
+
+
+tagfile                                             = ../../../doc/qtwebsockets/qtwebsockets.tags
+
+depends                                             += qtcore qtnetwork qtdoc
+
+headerdirs                                          += ..
+
+sourcedirs                                          += ..
+
+exampledirs                                         += ../../../examples/ \
+snippets
+
+navigation.landingpage                              = "Qt WebSockets"
+navigation.cppclassespage                           = "Qt WebSockets C++ Classes"
+
+#imagedirs                                          += ./images
diff --git a/src/websockets/doc/qwebsockets.qdoc b/src/websockets/doc/qwebsockets.qdoc
deleted file mode 100644
index 5406870..0000000
--- a/src/websockets/doc/qwebsockets.qdoc
+++ /dev/null
@@ -1,8 +0,0 @@
-/*!
-  \module QtWebSockets
-  \title QtWebSockets module
-
-  The QtWebSockets module implements the WebSocket protocol as specified in \l {http://tools.ietf.org/html/rfc6455} {RFC 6455}.
-  It solely depends on Qt (no external depencies).
-  The module contains 2 main classes: QWebSocket and QWebSocketServer, with which one can create client- and server applications.
- */
diff --git a/src/websockets/doc/qwebsockets.qdocconfig b/src/websockets/doc/qwebsockets.qdocconfig
deleted file mode 100644
index 33fde7d..0000000
--- a/src/websockets/doc/qwebsockets.qdocconfig
+++ /dev/null
@@ -1,23 +0,0 @@
-include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
-
-project     =  QWebSockets
-description =  QWebSockets Reference Documentation
-
-outputdir   =  html
-
-headerdirs  += ..
-headers     += ../qwebsocket.h \
-               ../qwebsocketserver.h
-
-sourcedirs  += ..
-sources     += ../qwebsocket.cpp \
-               ../qwebsocketserver.cpp \
-               qwebsockets.qdoc
-
-exampledirs += ../../../examples/ \
-               ../../../examples/echoclient \
-               ../../../examples/echoserver
-
-#imagedirs  += ./images
-
-depends     += qtdoc qtnetwork qtcore
\ No newline at end of file
diff --git a/src/websockets/doc/snippets/src_websockets_ssl_qwebsocket.cpp b/src/websockets/doc/snippets/src_websockets_ssl_qwebsocket.cpp
new file mode 100644
index 0000000..602ae8f
--- /dev/null
+++ b/src/websockets/doc/snippets/src_websockets_ssl_qwebsocket.cpp
@@ -0,0 +1,26 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Kurt Pattyn <pattyn.kurt@gmail.com>
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
diff --git a/src/websockets/doc/src/index.qdoc b/src/websockets/doc/src/index.qdoc
new file mode 100644
index 0000000..9f221e5
--- /dev/null
+++ b/src/websockets/doc/src/index.qdoc
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Kurt Pattyn <pattyn.kurt@gmail.com>
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtwebsockets-index.html
+    \since 5.2
+    \title Qt WebSockets
+    \brief Provides an implementation of the WebSocket protocol.
+
+    The QtWebSockets module implements the WebSocket protocol as specified in \l {http://tools.ietf.org/html/rfc6455} {RFC 6455}.
+    It solely depends on Qt (no external dependencies).
+
+
+    To use this module in your application, use the following include
+    statement:
+
+    \code
+    #include <QtWebSockets/QtWebSockets>
+    \endcode
+
+    To link against the module, add this line to your \l qmake \c
+    .pro file:
+
+    \code
+    QT += websockets
+    \endcode
+
+    \section1 Related information
+    \list
+    \li \l{Qt WebSockets C++ Classes}{C++ Classes}
+    \li \l{Qt WebSockets Examples}{Examples}
+    \endlist
+*/
diff --git a/src/websockets/doc/src/qtwebsockets-module.qdoc b/src/websockets/doc/src/qtwebsockets-module.qdoc
new file mode 100644
index 0000000..1d6c6f0
--- /dev/null
+++ b/src/websockets/doc/src/qtwebsockets-module.qdoc
@@ -0,0 +1,47 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Kurt Pattyn <pattyn.kurt@gmail.com>
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+    \module QtWebSockets
+    \title Qt WebSockets C++ Classes
+    \ingroup modules
+    \qtvariable websockets
+    \brief List of C++ classes that provice WebSockets communication.
+
+    To use these classes in your application, use the following include
+    statement:
+
+    \code
+    #include <QtWebSockets/QtWebSockets>
+    \endcode
+
+    To link against the module, add this line to your \l qmake \c
+    .pro file:
+
+    \code
+    QT += websockets
+    \endcode
+*/
diff --git a/src/websockets/qwebsocket.cpp b/src/websockets/qwebsocket.cpp
index 46c7776..18d1bb2 100644
--- a/src/websockets/qwebsocket.cpp
+++ b/src/websockets/qwebsocket.cpp
@@ -44,14 +44,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
     This example should ideally be used with the EchoServer example.
     \section1 Code
     We start by connecting to the `connected()` signal.
-    \snippet echoclient.cpp constructor
+    \snippet echoclient/echoclient.cpp constructor
     After the connection, we open the socket to the given \a url.
 
-    \snippet echoclient.cpp onConnected
+    \snippet echoclient/echoclient.cpp onConnected
     When the client is connected successfully, we connect to the `onTextMessageReceived()` signal, and send out "Hello, world!".
     If connected with the EchoServer, we will receive the same message back.
 
-    \snippet echoclient.cpp onTextMessageReceived
+    \snippet echoclient/echoclient.cpp onTextMessageReceived
     Whenever a message is received, we write it out.
 */
 
@@ -114,7 +114,7 @@ not been filled in with new information when the signal returns.
     The \a bytes argument is set to the number of bytes that were written in this payload.
 
     \note This signal has the same meaning both for secure and non-secure websockets.
-    As opposed to QSslSocket, bytesWritten() is only emitted when encrypted data is effectively written (\sa QSslSocket:encryptedBytesWritten()).
+    As opposed to QSslSocket, bytesWritten() is only emitted when encrypted data is effectively written (see QSslSocket:encryptedBytesWritten()).
     \sa close()
 */
 
@@ -167,6 +167,19 @@ not been filled in with new information when the signal returns.
     \sa error(), errorString()
 */
 /*!
+    \fn void QWebSocket::sslErrors(const QList<QSslError> &errors)
+    QWebSocket emits this signal after the SSL handshake to indicate that one or more errors have occurred
+    while establishing the identity of the peer.
+    The errors are usually an indication that QWebSocket is unable to securely identify the peer.
+    Unless any action is taken, the connection will be dropped after this signal has been emitted.
+    If you want to continue connecting despite the errors that have occurred, you must call QWebSocket::ignoreSslErrors() from inside a slot connected to this signal.
+    If you need to access the error list at a later point, you can call sslErrors() (without arguments).
+
+    \a errors contains one or more errors that prevent QWebSocket from verifying the identity of the peer.
+
+    \note You cannot use Qt::QueuedConnection when connecting to this signal, or calling QWebSocket::ignoreSslErrors() will have no effect.
+*/
+/*!
     \fn void QWebSocket::pong(quint64 elapsedTime, QByteArray payload)
 
     Emitted when a pong message is received in reply to a previous ping.
@@ -375,7 +388,7 @@ void QWebSocket::ignoreSslErrors()
     If, for instance, you want to connect to a server that uses
     a self-signed certificate, consider the following snippet:
 
-    \snippet src_websockets_ssl_qwebsocket 6
+    \snippet src_websockets_ssl_qwebsocket.cpp 6
 
     Multiple calls to this function will replace the list of errors that
     were passed in previous calls.
@@ -390,6 +403,32 @@ void QWebSocket::ignoreSslErrors(const QList<QSslError> &errors)
     d->ignoreSslErrors(errors);
 }
 
+/*!
+    Sets the socket's SSL configuration to be the contents of \a sslConfiguration.
+
+    This function sets the local certificate, the ciphers, the private key and the CA certificates to those stored in \a sslConfiguration.
+    It is not possible to set the SSL-state related fields.
+    \sa sslConfiguration()
+ */
+void QWebSocket::setSslConfiguration(const QSslConfiguration &sslConfiguration)
+{
+    Q_D(QWebSocket);
+    d->setSslConfiguration(sslConfiguration);
+}
+
+/*!
+    Returns the socket's SSL configuration state.
+    The default SSL configuration of a socket is to use the default ciphers, default CA certificates, no local private key or certificate.
+    The SSL configuration also contains fields that can change with time without notice.
+
+    \sa setSslConfiguration()
+ */
+QSslConfiguration QWebSocket::sslConfiguration() const
+{
+    Q_D(const QWebSocket);
+    return d->sslConfiguration();
+}
+
 #endif  //not QT_NO_SSL
 
 /*!
diff --git a/src/websockets/qwebsocketserver.cpp b/src/websockets/qwebsocketserver.cpp
index f267001..048e5da 100644
--- a/src/websockets/qwebsocketserver.cpp
+++ b/src/websockets/qwebsocketserver.cpp
@@ -52,22 +52,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
   The echoserver example implements a web socket server that echoes back everything that is sent to it.
   \section1 Code
   We start by creating a QWebSocketServer (`new QWebSocketServer()`). After the creation, we listen on all local network interfaces (`QHostAddress::Any`) on the specified \a port.
-  \snippet echoserver.cpp constructor
+  \snippet echoserver/echoserver.cpp constructor
   If listening is successful, we connect the `newConnection()` signal to the slot `onNewConnection()`.
   The `newConnection()` signal will be thrown whenever a new web socket client is connected to our server.
 
-  \snippet echoserver.cpp onNewConnection
+  \snippet echoserver/echoserver.cpp onNewConnection
   When a new connection is received, the client QWebSocket is retrieved (`nextPendingConnection()`), and the signals we are interested in
   are connected to our slots (`textMessageReceived()`, `binaryMessageReceived()` and `disconnected()`).
   The client socket is remembered in a list, in case we would like to use it later (in this example, nothing is done with it).
 
-  \snippet echoserver.cpp processMessage
+  \snippet echoserver/echoserver.cpp processMessage
   Whenever `processMessage()` is triggered, we retrieve the sender, and if valid, send back the original message (`send()`).
   The same is done with binary messages.
-  \snippet echoserver.cpp processBinaryMessage
+  \snippet echoserver/echoserver.cpp processBinaryMessage
   The only difference is that the message now is a QByteArray instead of a QString.
 
-  \snippet echoserver.cpp socketDisconnected
+  \snippet echoserver/echoserver.cpp socketDisconnected
   Whenever a socket is disconnected, we remove it from the clients list and delete the socket.
   Note: it is best to use `deleteLater()` to delete the socket.
 */
diff --git a/src/websockets/websockets.pro b/src/websockets/websockets.pro
index 5ba40c1..25944f1 100644
--- a/src/websockets/websockets.pro
+++ b/src/websockets/websockets.pro
@@ -1,14 +1,15 @@
-QT += network
-
+load(qt_build_config)
 TARGET = QtWebSockets
 
-TEMPLATE += lib
+QT += core network
 
-DEFINES += QTWEBSOCKETS_LIBRARY
+TEMPLATE = lib
 
-load(qt_module)
+DEFINES += QTWEBSOCKETS_LIBRARY
 
-QMAKE_DOCS = $$PWD/doc/qwebsockets.qdocconfig
+QMAKE_DOCS = $$PWD/doc/qtwebsockets.qdocconfig
+OTHER_FILES += doc/src/*.qdoc   # show .qdoc files in Qt Creator
+OTHER_FILES += doc/snippets/*.cpp
 
 PUBLIC_HEADERS += \
     $$PWD/qwebsockets_global.h \
@@ -39,3 +40,5 @@ SOURCES += \
     $$PWD/qwebsocketframe_p.cpp
 
 HEADERS += $$PUBLIC_HEADERS $$PRIVATE_HEADERS
+
+load(qt_module)
diff --git a/websockets.pro b/websockets.pro
index 58c33f2..0c67e66 100644
--- a/websockets.pro
+++ b/websockets.pro
@@ -1 +1,2 @@
+load(configure)
 load(qt_parts)