Cleaned up documentation

Change-Id: Ib79c0d8ccfd0fb332f768b4ea27507ca20dd7d69
Reviewed-by: Chris Craig <ext-chris.craig@nokia.com>

12 files changed, 158 insertions, 91 deletions

diff --git a/doc/jsonstream.qdocconf b/doc/jsonstream.qdocconf
index ac39078..bd816dc 100644
--- a/doc/jsonstream.qdocconf
+++ b/doc/jsonstream.qdocconf
@@ -1,4 +1,4 @@
-alias.i = e
+# alias.i = e
 
 project     = JsonStream
 description = JSONStream Manager Documentation
diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc
index c928256..7f66704 100644
--- a/doc/src/index.qdoc
+++ b/doc/src/index.qdoc
@@ -38,11 +38,11 @@ Javascript-based programming languages is to use \l
 {http://www.json.org} {JSON} data-interchange format.
 The JSON Stream classes implement a client/server framework.
 
-\bold{Discussion and examples}
+\b{Discussion and examples}
 \list
- \o \l{Stream serialization}
- \o \l{Using JSON stream classes}
- \o \l{Authority notes}
+ \li \l{Stream serialization}
+ \li \l{Using JSON stream classes}
+ \li \l{Authority notes}
 \endlist
 
 The JSON Stream classes depend on the Qt Json experimental JSON module.
diff --git a/doc/src/jsonstreamnamespace.qdoc b/doc/src/jsonstreamnamespace.qdoc
index 50a382d..cff9499 100644
--- a/doc/src/jsonstreamnamespace.qdoc
+++ b/doc/src/jsonstreamnamespace.qdoc
@@ -46,6 +46,15 @@
 */
 
 /*!
+  \headerfile <jsonstream-global.h>
+  \title Global JsonStream declarations
+
+  \brief The <jsonstream-global.h> file provides namespace
+         declarations and global enumerations for JsonStream.
+ */
+
+/*!
+  \relates <jsonstream-global.h>
   \enum EncodingFormat
 
   This enum is used to control the serialization format of the data stream.
diff --git a/doc/src/serialization.qdoc b/doc/src/serialization.qdoc
index eefd41a..7d1365f 100644
--- a/doc/src/serialization.qdoc
+++ b/doc/src/serialization.qdoc
@@ -35,17 +35,17 @@
 One key challenge with JSON is that there are a number of different
 ways that JSON can be serialized to be sent over a socket connection:
 \list
- \o UTF-8 encoded (the default)
- \o UTF-16 LE or BE
- \o UTF-32 LE or BE
- \o \l {http://bsonspec.org} {BSON} (Binary JSON)
- \o \l Qt Json [ssh://codereview.qt-project.org:29418/playground/qtbinaryjson.git]
+ \li UTF-8 encoded (the default)
+ \li UTF-16 LE or BE
+ \li UTF-32 LE or BE
+ \li \l {http://bsonspec.org} {BSON} (Binary JSON)
+ \li \l Qt Json [ssh://codereview.qt-project.org:29418/playground/qtbinaryjson.git]
 \endlist
 For a discussion of the UTF encoding formats, see \l
 {http://www.ietf.org/rfc/rfc4627} {RFC4627}.
 
 The JSON stream reference supports all standard encoding formats by
-\bold{auto-detection}.  The server class assumes that communication
+\b{auto-detection}.  The server class assumes that communication
 will be initiated by the client. The initial bytes received are
 matched to the signature of one of the serialization techniques and
 the connection is set to that format.
@@ -54,50 +54,50 @@ To be specific, the server matches (table data from \l
 {http://www.ietf.org/rfc/rfc4627} {RFC4627}):
 \table
 \header
-  \o Encoding
-  \o Bytes
-  \o Discussion
+  \li Encoding
+  \li Bytes
+  \li Discussion
 \row
-  \o UTF-8
-  \o 7B xx yy zz
-  \o First byte should be the '{' character, followed by whitespace
+  \li UTF-8
+  \li 7B xx yy zz
+  \li First byte should be the '{' character, followed by whitespace
      and a '"' quotation mark.
 \row
-  \o BSON
-  \o 62 73 6F 6E
-  \o First four bytes are 'bson'.  Strictly speaking, this is
+  \li BSON
+  \li 62 73 6F 6E
+  \li First four bytes are 'bson'.  Strictly speaking, this is
      not the true BSON format (which starts with an int32 length)
      but in the interests of autodetection we've enforced this
      requirement.  The BSON packet follows.
 \row
-  \o QBJS
-  \o 71 62 6A 73
-  \o First four bytes are 'qbjs'.  This matches the standard
+  \li QBJS
+  \li 71 62 6A 73
+  \li First four bytes are 'qbjs'.  This matches the standard
      QtJson::JsonDocument header.
 \row
-  \o UTF-32BE
-  \o 00 00 00 7B
-  \o First four bytes should be the '{' character
+  \li UTF-32BE
+  \li 00 00 00 7B
+  \li First four bytes should be the '{' character
 \row
-  \o UTF-32LE
-  \o 7B 00 00 00
-  \o First four bytes should be the '{' character.
+  \li UTF-32LE
+  \li 7B 00 00 00
+  \li First four bytes should be the '{' character.
 \row
-  \o Raw UTF-16BE
-  \o 00 7B 00 xx
-  \o First two bytes should be the '{' character.
+  \li Raw UTF-16BE
+  \li 00 7B 00 xx
+  \li First two bytes should be the '{' character.
 \row
-  \o Raw UTF-16LE
-  \o 7B 00 xx 00
-  \o First two bytes should be the '{' character.
+  \li Raw UTF-16LE
+  \li 7B 00 xx 00
+  \li First two bytes should be the '{' character.
 \row
-  \o UTF-16BE with BOM
-  \o FE FF 00 7B
-  \o U+FEFF + '{'
+  \li UTF-16BE with BOM
+  \li FE FF 00 7B
+  \li U+FEFF + '{'
 \row
-  \o UTF-16LE with BOM
-  \o FF FE 7B 00
-  \o U+FEFF + '{'
+  \li UTF-16LE with BOM
+  \li FF FE 7B 00
+  \li U+FEFF + '{'
 \endtable
 
 Clearly, there is a danger that the BSON encoding format could be
diff --git a/src/jsonclient.cpp b/src/jsonclient.cpp
index b5cdd24..7f1d1f4 100644
--- a/src/jsonclient.cpp
+++ b/src/jsonclient.cpp
@@ -52,9 +52,6 @@ QT_BEGIN_NAMESPACE_JSONSTREAM
 
 /****************************************************************************/
 
-/*!
-  \internal
-*/
 class JsonClientPrivate
 {
 public:
diff --git a/src/jsonpipe.cpp b/src/jsonpipe.cpp
index cf76e0f..58fb15c 100644
--- a/src/jsonpipe.cpp
+++ b/src/jsonpipe.cpp
@@ -58,9 +58,6 @@ QT_BEGIN_NAMESPACE_JSONSTREAM
 
 /****************************************************************************/
 
-/*!
-  \internal
-*/
 class JsonPipePrivate
 {
 public:
@@ -88,6 +85,18 @@ public:
 */
 
 /*!
+    \enum JsonPipe::PipeError
+
+    This enum is passed in the \l{error()} signal indicating a problem
+    with a pipe connection.
+
+    \value WriteFailed  Unable to write to the outgoing pipe
+    \value WriteAtEnd   The outgoing pipe has been closed
+    \value ReadFailed   Unable to read from the incoming pipe
+    \value ReadAtEnd    The incoming pipe has been closed
+ */
+
+/*!
   Constructs a \c JsonPipe object with an optional \a parent.
  */
 
@@ -130,7 +139,8 @@ bool JsonPipe::readEnabled() const
 }
 
 /*!
-  Set the current file descriptors
+  Set the current file descriptors.  The input descriptor is set to \a
+  in_fd and the output descriptor is set to \a out_fd.
 */
 
 void JsonPipe::setFds(int in_fd, int out_fd)
@@ -149,6 +159,10 @@ void JsonPipe::setFds(int in_fd, int out_fd)
     d->mOut->setEnabled(d->mOutBuffer.size() > 0);
 }
 
+/*!
+  \internal
+ */
+
 void JsonPipe::inReady(int fd)
 {
     Q_D(JsonPipe);
@@ -190,6 +204,10 @@ int JsonPipe::writeInternal(int fd)
     return n;
 }
 
+/*!
+  \internal
+*/
+
 void JsonPipe::outReady(int)
 {
     Q_D(JsonPipe);
@@ -203,7 +221,9 @@ void JsonPipe::outReady(int)
 }
 
 /*!
-  Send a JsonObject \a object over the pipe
+  Send a JsonObject \a object over the pipe.  Return true if
+  the object could be added to the output buffer and false if there is
+  no output buffer.
 */
 
 bool JsonPipe::send(const QJsonObject& object)
@@ -270,10 +290,11 @@ void JsonPipe::setFormat( EncodingFormat format )
     d->mFormat = format;
 }
 
-/*
+/*!
   Blocks until all of the output buffer has been written to the pipe.
   We return true if and only if there was data to be written and it
-  was successfully written.
+  was successfully written.  The \a msecs parameter is the maximum
+  number of milliseconds to block before giving up.
  */
 
 bool JsonPipe::waitForBytesWritten(int msecs)
@@ -314,17 +335,15 @@ bool JsonPipe::waitForBytesWritten(int msecs)
 }
 
 /*!
-    Sends the \a map via the pipe.
-    The QVariant types allowed are restricted to basic types supported
-    by the BsonObject which is in principle bool, int, long, QString and
-    arrays and maps of them.
+  \relates JsonPipe
 
-    \sa BsonObject
+    Sends the \a map via the \a pipe.
 */
-JsonPipe& operator<<( JsonPipe& s, const QJsonObject& map )
+
+JsonPipe& operator<<( JsonPipe& pipe, const QJsonObject& map )
 {
-    s.send(map);
-    return s;
+    pipe.send(map);
+    return pipe;
 }
 
 /*!
@@ -334,10 +353,9 @@ JsonPipe& operator<<( JsonPipe& s, const QJsonObject& map )
 */
 
 /*!
-    \fn void JsonPipe::aboutToClose()
-    This signal is emitted when the underlying \c QIODevice is about to close.
-
-    \sa QIODevice
+    \fn void JsonPipe::error(PipeError err)
+    This signal is emitted when there is a read or write pipe error \a
+    err.
 */
 
 #include "moc_jsonpipe.cpp"
diff --git a/src/jsonpipe.h b/src/jsonpipe.h
index ff2ac93..63bf387 100644
--- a/src/jsonpipe.h
+++ b/src/jsonpipe.h
@@ -84,9 +84,6 @@ protected slots:
     void inReady(int fd);
     void outReady(int fd);
 
-protected:
-    void sendInternal(const QByteArray& byteArray);
-
 private:
     int writeInternal(int fd);
 
diff --git a/src/jsonserver.cpp b/src/jsonserver.cpp
index 0c2be1d..f258cf9 100644
--- a/src/jsonserver.cpp
+++ b/src/jsonserver.cpp
@@ -104,9 +104,9 @@ public:
     It consists of the following components:
 
     \list
-       \o JsonClient, a client-side class which sends and receives JSON messages
-       \o JsonServer, the server class which sends and receives JSON messages
-       \o JsonAuthority, an abstract authorization class which
+       \li JsonClient, a client-side class which sends and receives JSON messages
+       \li JsonServer, the server class which sends and receives JSON messages
+       \li JsonAuthority, an abstract authorization class which
           approves connections from clients and assigns client names.
     \endlist
 
@@ -174,7 +174,7 @@ bool JsonServer::listen( int port, JsonAuthority *authority )
   If the \a authority is omitted or NULL, all connections will be automatically authorized and
   a unique identifier generated for each new connection. Returns true if the socket could be opened.
 
-  Does \bold{not} take ownership of the \a authority object.
+  Does \b{not} take ownership of the \a authority object.
  */
 bool JsonServer::listen(const QString &socketname, JsonAuthority *authority)
 {
@@ -398,7 +398,7 @@ void JsonServer::disableMultipleConnections(const QString& identifier)
 
 /*!
     Sends an arbitrary \a message to the client application identified by \a identifier and returns true when
-    the client was found and the message could be sent. The return value does \bold{not} indicate that
+    the client was found and the message could be sent. The return value does \b{not} indicate that
     the client actually received the message and reacted to it, only that the JsonServer had a connection
     open to that client, and was able to dispatch the message.
 
diff --git a/src/jsonserverclient.cpp b/src/jsonserverclient.cpp
index 09e4c55..73fff00 100644
--- a/src/jsonserverclient.cpp
+++ b/src/jsonserverclient.cpp
@@ -48,10 +48,6 @@
 
 QT_BEGIN_NAMESPACE_JSONSTREAM
 
-
-/*!
-  \internal
-*/
 class JsonServerClientPrivate
 {
 public:
@@ -67,12 +63,25 @@ public:
 
 /****************************************************************************/
 
+/*!
+  \class JsonServerClient
+  \brief The JsonServerClient class wraps an individual connection to the JsonServer.
+ */
+
+/*!
+  Construct a JsonServerClient object with the given \a parent
+ */
+
 JsonServerClient::JsonServerClient(QObject *parent)
     : QObject(parent)
     , d_ptr(new JsonServerClientPrivate())
 {
 }
 
+/*!
+  Destructs the JsonServerClient object.
+ */
+
 JsonServerClient::~JsonServerClient()
 {
 }
@@ -88,12 +97,20 @@ void JsonServerClient::setAuthority(JsonAuthority *authority)
     d->m_authority = authority;
 }
 
+/*!
+  Return the internal socket object
+*/
+
 const QLocalSocket *JsonServerClient::socket() const
 {
     Q_D(const JsonServerClient);
     return d->m_socket;
 }
 
+/*!
+  Set the internal socket object to \a socket.
+ */
+
 void JsonServerClient::setSocket(QLocalSocket *socket)
 {
     Q_D(JsonServerClient);
@@ -109,12 +126,21 @@ void JsonServerClient::setSocket(QLocalSocket *socket)
     }
 }
 
+/*!
+  Return the client identifier
+ */
+
 QString JsonServerClient::identifier() const
 {
     Q_D(const JsonServerClient);
     return d->m_identifier;
 }
 
+/*!
+  Start processing messages from this client.  This function should
+  only be called by the \l{JsonServer}
+ */
+
 void JsonServerClient::start()
 {
     Q_D(JsonServerClient);
@@ -181,6 +207,10 @@ void JsonServerClient::received(const QJsonObject& message)
     }
 }
 
+/*!
+  Send a \a message to the client.
+ */
+
 void JsonServerClient::send(const QJsonObject &message)
 {
     Q_D(JsonServerClient);
@@ -202,6 +232,32 @@ void JsonServerClient::handleDisconnect()
     // qDebug() << Q_FUNC_INFO << "done";
 }
 
+/*!
+  \fn JsonServerClient::disconnected(const QString& identifier)
+  This signal is emitted when the client has been disconnected.  The
+  \a identifier property is included for convenience.
+ */
+
+/*!
+  \fn JsonServerClient::messageReceived(const QString& identifier, const QJsonObject& message)
+
+  This signal is emitted when a \a message has been received by the client. The
+  \a identifier property is included for convenience.
+ */
+
+/*!
+  \fn JsonServerClient::authorized(const QString& identifier)
+
+  This signal is emitted when the client has been authorized. The
+  \a identifier property is included for convenience.
+ */
+
+/*!
+  \fn JsonServerClient::authorizationFailed()
+
+  This signal is emitted when the client has failed authorization.
+ */
+
 #include "moc_jsonserverclient.cpp"
 
 QT_END_NAMESPACE_JSONSTREAM
diff --git a/src/jsonserverclient.h b/src/jsonserverclient.h
index 7ee167d..00b7394 100644
--- a/src/jsonserverclient.h
+++ b/src/jsonserverclient.h
@@ -73,8 +73,6 @@ public:
 
     QString identifier() const;
 
-    QList<QJsonObject> messageQueue() const;
-
 signals:
     void disconnected(const QString& identifier);
     void messageReceived(const QString& identifier, const QJsonObject& message);
diff --git a/src/jsonstream.cpp b/src/jsonstream.cpp
index e11673e..0fe966a 100644
--- a/src/jsonstream.cpp
+++ b/src/jsonstream.cpp
@@ -68,9 +68,6 @@ static QByteArray bsonToByteArray(BsonObject &bson)
 
 /****************************************************************************/
 
-/*!
-  \internal
-*/
 class JsonStreamPrivate
 {
 public:
@@ -271,17 +268,14 @@ void JsonStream::setFormat( EncodingFormat format )
 
 
 /*!
-    Sends the \a map via the stream.
-    The QVariant types allowed are restricted to basic types supported
-    by the BsonObject which is in principle bool, int, long, QString and
-    arrays and maps of them.
+    \relates JsonStream
 
-    \sa BsonObject
+    Sends the \a map via the \a stream.
 */
-JsonStream& operator<<( JsonStream& s, const QJsonObject& map )
+JsonStream& operator<<( JsonStream& stream, const QJsonObject& map )
 {
-    s.send(map);
-    return s;
+    stream.send(map);
+    return stream;
 }
 
 
@@ -294,8 +288,6 @@ JsonStream& operator<<( JsonStream& s, const QJsonObject& map )
 /*!
     \fn void JsonStream::aboutToClose()
     This signal is emitted when the underlying \c QIODevice is about to close.
-
-    \sa QIODevice
 */
 
 #include "moc_jsonstream.cpp"
diff --git a/src/jsontokenauthority.cpp b/src/jsontokenauthority.cpp
index 1ba0cb6..c17e2ef 100644
--- a/src/jsontokenauthority.cpp
+++ b/src/jsontokenauthority.cpp
@@ -86,7 +86,7 @@ bool JsonTokenAuthority::authorize(const QByteArray &token, const QString &ident
 
 /*!
     Remove a \a token from the valid hash table.  Calling this function does
-    \bold{not} disconnect any existing clients.  Return true if the token was in the table, false if it was not.
+    \b{not} disconnect any existing clients.  Return true if the token was in the table, false if it was not.
 */
 bool JsonTokenAuthority::deauthorize(const QByteArray &token)
 {