From b67de54325d2ded4e9b685662036dfd0835fa49b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Tue, 4 Aug 2015 21:39:19 +0200 Subject: [PATCH] fix dokumentation --- doc/guhserver.qdoc | 4 +- libguh/types/paramdescriptor.cpp | 2 +- server/guhcore.cpp | 2 + server/httpreply.cpp | 72 ++++++++++++++++++++------------ server/httprequest.cpp | 57 +++++++++++++++++++++++++ server/logging/logentry.cpp | 4 ++ 6 files changed, 113 insertions(+), 28 deletions(-) diff --git a/doc/guhserver.qdoc b/doc/guhserver.qdoc index 41c90a8b..6ce2299c 100644 --- a/doc/guhserver.qdoc +++ b/doc/guhserver.qdoc @@ -1,7 +1,9 @@ /*! \namespace guhserver - \brief The namespace for the server. + \brief The namespace for the guh server. \inmodule server + + This namespace represents the whole guh server. This prevents duplicated classnames in plugin and core. */ diff --git a/libguh/types/paramdescriptor.cpp b/libguh/types/paramdescriptor.cpp index 320b3121..5f2bc288 100644 --- a/libguh/types/paramdescriptor.cpp +++ b/libguh/types/paramdescriptor.cpp @@ -26,7 +26,7 @@ \ingroup types \inmodule libguh - An ParamDescriptor describes a \l{Param} in order to match it with a \l{guhserver::yRule}. + An ParamDescriptor describes a \l{Param} in order to match it with a \l{guhserver::Rule}. \sa Param, ParamType */ diff --git a/server/guhcore.cpp b/server/guhcore.cpp index 4ca6b1c5..eb370fac 100644 --- a/server/guhcore.cpp +++ b/server/guhcore.cpp @@ -524,11 +524,13 @@ LogEngine* GuhCore::logEngine() const return m_logger; } +/*! Returns the pointer to the \l{JsonRPCServer} of this instance. */ JsonRPCServer *GuhCore::jsonRPCServer() const { return m_serverManager->jsonServer(); } +/*! Returns the pointer to the \l{RestServer} of this instance. */ RestServer *GuhCore::restServer() const { return m_serverManager->restServer(); diff --git a/server/httpreply.cpp b/server/httpreply.cpp index 40bf40c4..527465fb 100644 --- a/server/httpreply.cpp +++ b/server/httpreply.cpp @@ -36,68 +36,82 @@ This enum type specifies the status code of a HTTP webserver reply. + You can find more information here: \l{http://tools.ietf.org/html/rfc7231#section-6.1}{http://tools.ietf.org/html/rfc7231#section-6.1} + \value Ok The request was understood and everything is Ok. \value Created - ... + The resource was created sucessfully. \value Accepted - ... + The resource was accepted. \value NoContent - ... + The request has no content but it was expected. \value Found - ... + The resource was found. \value BadRequest - ... + The request was bad formatted. Also if a \l{Param} was not understood or the header is not correct. \value Forbidden - ... + The request tries to get access to a forbidden space. \value NotFound - ... + The requested resource could not be found. \value MethodNotAllowed - ... + The request method is not allowed. See "Allowed-Methods" header for the allowed methods. \value RequestTimeout - ... + The request method timed out. Default timeout = 5s. \value Conflict - ... + The request resource conflicts with an other. \value InternalServerError - ... + There was an internal server error. \value NotImplemented - ... + The requestet method call is not implemented. \value BadGateway - ... + The gateway is not correct. \value ServiceUnavailable - ... + The service is not available at the moment. \value GatewayTimeout - ... + The gateway timed out. \value HttpVersionNotSupported - ... + The HTTP version is not supported. The only supported version is HTTP/1.1. */ /*! \enum guhserver::HttpReply::HttpHeaderType This enum type specifies the known type of a header in a HTTP webserver reply. + You can find more information here: \l{http://tools.ietf.org/html/rfc7231#section-5} + \value ContentTypeHeader - The request was understood and everything is Ok. + The content type header i.e. application/json. \value ContentLenghtHeader - ... + The length of the sent content. \value ConnectionHeader - ... + The connection header. \value LocationHeader - ... + The location header. \value UserAgentHeader - ... + The user agent of the client. \value CacheControlHeader - ... + The cache control header. \value AllowHeader - ... + The allowed methods header. \value DateHeader - ... + The server date header. \value ServerHeader - ... + The name of the server i.e. "Server: guh/0.6.0" */ /*! \enum guhserver::HttpReply::Type + This enum type describes the type of this \l{HttpReply}. There are two types: + + \value TypeSync + The \l{HttpReply} can be responded imediatly. + \value TypeAsync + The \l{HttpReply} is asynchron and has to be responded later. +*/ + +/*! \fn void guhserver::HttpReply::finished(); + This signal is emitted when this async \l{HttpReply} is finished. */ #include "httpreply.h" @@ -108,7 +122,7 @@ namespace guhserver { -/*! Construct a HttpReply with the given \a statusCode. */ +/*! Construct an empty \l{HttpReply} with the given \a parent. */ HttpReply::HttpReply(QObject *parent) : QObject(parent), m_statusCode(HttpReply::Ok), @@ -128,6 +142,7 @@ HttpReply::HttpReply(QObject *parent) : packReply(); } +/*! Construct a \l{HttpReply} with the given \a statusCode, \a type and \a parent. */ HttpReply::HttpReply(const HttpReply::HttpStatusCode &statusCode, const HttpReply::Type &type, QObject *parent): QObject(parent), m_statusCode(statusCode), @@ -160,6 +175,7 @@ HttpReply::HttpStatusCode HttpReply::httpStatusCode() const return m_statusCode; } +/*! Returns the error code reason phrase for the current \l{HttpStatusCode}.*/ QByteArray HttpReply::httpReasonPhrase() const { return m_reasonPhrase; @@ -173,11 +189,13 @@ HttpReply::Type HttpReply::type() const return m_type; } +/*! Set the \a clientId of this \l{HttpReply}.*/ void HttpReply::setClientId(const QUuid &clientId) { m_clientId = clientId; } +/*! Returns the clientId of this \l{HttpReply}.*/ QUuid HttpReply::clientId() const { return m_clientId; @@ -265,11 +283,13 @@ void HttpReply::packReply() m_data = m_rawHeader.append(m_payload); } +/*! Returns the current raw data (header + payload) of this \l{HttpReply}.*/ QByteArray HttpReply::data() const { return m_data; } +/*! Return true if the response took to long for the request.*/ bool HttpReply::timedOut() const { return m_timedOut; diff --git a/server/httprequest.cpp b/server/httprequest.cpp index 96597bcf..e5ef700d 100644 --- a/server/httprequest.cpp +++ b/server/httprequest.cpp @@ -18,6 +18,39 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class guhserver::HttpRequest + \brief Represents a HTTP request from a client to the guh \l{WebServer}. + + \ingroup core + \inmodule server + + This class holds the header and the payload data of a network request from a client to the \l{WebServer}. + + \note RFC 7231 HTTP/1.1 Semantics and Content -> \l{http://tools.ietf.org/html/rfc7231}{http://tools.ietf.org/html/rfc7231} + +*/ + +/*! \enum guhserver::HttpRequest::RequestMethod + + This enum type describes the method of a \l{HttpRequest}. Following methods are allowed/handled: + + \value Get + Represents the HTTP/1.1 GET method. + \value Post + Represents the HTTP/1.1 POST method. + \value Put + Represents the HTTP/1.1 PUT method. + \value Delete + Represents the HTTP/1.1 DELETE method. + \value Unhandled + Represents every other method which is not handled. +*/ + +/*! \fn QDebug guhserver::operator<< (QDebug debug, const HttpRequest &httpRequest); + Writes the \l{HttpRequest} \a httpRequest to the given \a debug. This method gets used just for debugging. +*/ + #include "httprequest.h" #include "loggingcategories.h" @@ -25,6 +58,7 @@ namespace guhserver { +/*! Construct an empty \l{HttpRequest}. */ HttpRequest::HttpRequest() : m_rawData(QByteArray()), m_valid(false), @@ -32,6 +66,11 @@ HttpRequest::HttpRequest() : { } +/*! Construct a \l{HttpRequest} with the given \a rawData. The \a rawData will be parsed in this constructor. You can check + if the data is valid with \l{isValid()}. You can check if the request is complete with \l{isComplete}. + + \sa isValid(), isComplete() +*/ HttpRequest::HttpRequest(QByteArray rawData) : m_rawData(rawData), m_valid(false), @@ -40,61 +79,79 @@ HttpRequest::HttpRequest(QByteArray rawData) : validate(); } +/*! Returns the raw header of this request.*/ QByteArray HttpRequest::rawHeader() const { return m_rawHeader; } +/*! Returns the list of raw header splitted into key and value.*/ QHash HttpRequest::rawHeaderList() const { return m_rawHeaderList; } +/*! Returns the \l{RequestMethod} of this request. + + \sa RequestMethod +*/ HttpRequest::RequestMethod HttpRequest::method() const { return m_method; } +/*! Returns the method as human readable string.*/ QString HttpRequest::methodString() const { return m_methodString; } +/*! Returns the HTTP version of this \l{HttpRequest}.*/ QByteArray HttpRequest::httpVersion() const { return m_httpVersion; } +/*! Returns the URL of this \l{HttpRequest}.*/ QUrl HttpRequest::url() const { return m_url; } +/*! Returns the URL query of this \l{HttpRequest}.*/ QUrlQuery HttpRequest::urlQuery() const { return m_urlQuery; } +/*! Returns the payload (content) of this \l{HttpRequest}.*/ QByteArray HttpRequest::payload() const { return m_payload; } +/*! Returns true if this \l{HttpRequest} is valid. A HTTP request is valid if the header and the payload were paresed successfully without errors.*/ bool HttpRequest::isValid() const { return m_valid; } +/*! Returns true if this \l{HttpRequest} is complete. A HTTP request is complete if "Content-Length" header value matches the actual payload size. Bigger packages will be sent in multiple TCP packages. */ bool HttpRequest::isComplete() const { return m_isComplete; } +/*! Returns true if this \l{HttpRequest} has a payload.*/ bool HttpRequest::hasPayload() const { return !m_payload.isEmpty(); } +/*! Appends data to the current raw data of this \l{HttpRequest}. This method will be used if a \l{HttpRequest} is not complete yet. + + \sa isComplete() +*/ void HttpRequest::appendData(const QByteArray &data) { m_rawData.append(data); diff --git a/server/logging/logentry.cpp b/server/logging/logentry.cpp index da70a551..2961e570 100644 --- a/server/logging/logentry.cpp +++ b/server/logging/logentry.cpp @@ -19,6 +19,10 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! \fn QDebug guhserver::operator<< (QDebug dbg, const LogEntry &entry);; + Writes the \l{LogEntry} \a entry to the given \a dbg. This method gets used just for debugging. +*/ + #include "logentry.h" #include "jsonrpc/jsontypes.h"