Server refactoring: Fix doc and comments

    Fix typo in doc and comments
    Update documentation
    Fix return of implicitely shared objects
    Fix order of parameters in QgsServiceRegistry::registerService

python/server/qgsserverrequest.sip

@@ -1,7 +1,7 @@
 /***************************************************************************
                           qgsserverrequest.h
 
-  Define ruquest class for getting request contents
+  Define request class for getting request contents
   -------------------
   begin                : 2016-12-05
   copyright            : (C) 2016 by David Marteau
@@ -20,11 +20,9 @@
 /**
  * \ingroup server
  * QgsServerRequest
- * Class defining request intreface passed to services QgsService::executeRequest() method
- *
- *  Note about design: this intreface must be passed along to python and thus signatures methods must be 
- *  compatible with pyQGS/pyQT api and rules.
+ * Class defining request interface passed to services QgsService::executeRequest() method
  */
+
 class QgsServerRequest
 {
 %TypeHeaderCode
@@ -48,29 +46,29 @@ class QgsServerRequest
         * Constructor
         *
         * @param url QUrl
-        * @param method the rquest method
+        * @param method the request method (default to GetMethod)
         */
-       QgsServerRequest( const QUrl& url, Method method );
+       QgsServerRequest( const QUrl& url, Method method = GetMethod );
 
        //! destructor
        virtual ~QgsServerRequest();
 
        /**
-        * @return  the request url
+        * @return the request url
         */
-       virtual const QUrl& url() const; 
+       virtual QUrl url() const; 
 
        /**
-        * @return the rquest method
+        * @return the request method
         */
        virtual Method method() const;
 
        /**
         * Return post/put data
-        * The default implementation retfurn nullptr
-        * @return a QByteArray pointer or nullptr
+        * Check for QByteArray::isNull() to check if data
+        * is available.
         */
-       virtual const QByteArray* data() const;
+       virtual QByteArray data() const;
 
 };
 

python/server/qgsserverresponse.sip

@@ -1,5 +1,5 @@
 /***************************************************************************
-                          qgsserverresponse.h
+                          qgsserverresponse.sip
 
   Define response class for services
   -------------------
@@ -21,12 +21,8 @@
  * \ingroup server
  * QgsServerResponse
  * Class defining response interface passed to services QgsService::executeRequest() method
- *
- *  Note:
- *  This class is intended to be used from python code: method signatures and return types should be 
- *  compatible with pyQGIS/pyQT types and rules.
- *
  */
+
 class QgsServerResponse
 {
 %TypeHeaderCode
@@ -40,34 +36,41 @@ class QgsServerResponse
         //! destructor
         virtual ~QgsServerResponse();
 
-       /** Set header entry 
-        *  Add header entry to the response 
-        *  Note that it is usually an error to set hedaer after writng data
+       /** Set Header entry 
+        *  Add Header entry to the response 
+        *  Note that it is usually an error to set Header after writng data
         */
         virtual void setHeader( const QString& key, const QString& value ) = 0;
 
-       /** Set the http return code 
+       /** Set the http return code
+        * @param code HTTP return code value
         */
         virtual void setReturnCode( int code ) = 0;
 
         /**
-         * Send error 
+         * Send error
+         * This method delegate error handling at the server level. This is different
+         * from calling setReturnCodei() along with and a specific response body.
+         * @param code HHTP return code value
+         * @param message An informative error message
          */
         virtual void sendError( int code,  const QString& message ) = 0;
 
         /**
-         * Write string 
+         * Write string
+         * This is a convenient method that will write directly
+         * to the underlying I/O device
          */
         virtual void write(const QString& data );
 
        /**
-        * Write chunk af data
-        * They are convenience method that will write directly to the 
+        * Write chunk of data
+        * They is a convenient method that will write directly to the 
         * underlying I/O device
-        */
+        * @return the number of bytes that were actually writtene
+        */ 
         virtual qint64 write(const QByteArray& byteArray );
 
-
         /**
          * Return the underlying QIODevice
          */

python/server/qgsserviceregistry.sip

@@ -62,7 +62,7 @@ class QgsServiceRegistry
      * @param service a QgsServerResponse to be registered
      * @param version the service version 
      */
-    void registerService( const QString& name,  QgsService* service /Transfer/, const QString& version );
+    void registerService( const QString& name,  const QString& version, QgsService* service /Transfer/ );
 
     /** 
      * Initialize registry, load modules and auto register services

src/server/qgsserverrequest.cpp

@@ -40,7 +40,7 @@ QgsServerRequest::~QgsServerRequest()
 
 }
 
-const QUrl& QgsServerRequest::url() const 
+QUrl QgsServerRequest::url() const 
 {
     return mUrl;
 }
@@ -50,9 +50,9 @@ QgsServerRequest::Method QgsServerRequest::method() const
     return mMethod;
 }
 
-const QByteArray* QgsServerRequest::data() const
+QByteArray QgsServerRequest::data() const
 {
-    return nullptr;
+    return QByteArray();
 }
 
 

src/server/qgsserverrequest.h

@@ -1,7 +1,7 @@
 /***************************************************************************
                           qgsserverrequest.h
 
-  Define ruquest class for getting request contents
+  Define request class for getting request contents
   -------------------
   begin                : 2016-12-05
   copyright            : (C) 2016 by David Marteau
@@ -24,11 +24,12 @@
 /**
  * \ingroup server
  * QgsServerRequest
- * Class defining request intreface passed to services QgsService::executeRequest() method
- *
- *  Note about design: this intreface must be passed along to python and thus signatures methods must be 
- *  compatible with pyQGS/pyQT api and rules.
+ * Class defining request interface passed to services QgsService::executeRequest() method
  */
+
+// Note about design: this intreface must be passed along to python and thus signatures methods must be 
+// compatible with pyQGS/pyQT api and rules.
+
 class SERVER_EXPORT QgsServerRequest
 {
     public:
@@ -49,32 +50,31 @@ class SERVER_EXPORT QgsServerRequest
         * Constructor
         *
         * @param url QUrl
-        * @param method the rquest method
+        * @param method the request method
         */
-       QgsServerRequest( const QUrl& url, Method method );
+       QgsServerRequest( const QUrl& url, Method method = GetMethod );
 
        //! destructor
        virtual ~QgsServerRequest();
 
        /**
         * @return  the request url
         */
-       virtual const QUrl& url() const; 
+       virtual QUrl url() const; 
 
        /**
-        * @return the rquest method
+        * @return the request method
         */
        virtual Method method() const;
 
        /**
         * Return post/put data
-        * The default implementation retfurn nullptr
-        * @return a QByteArray pointer or nullptr
+        * Check for QByteArray::isNull() to check if data
+        * is available.
         */
-        virtual const QByteArray* data() const;
+        virtual QByteArray data() const;
 
     protected:
-
         QUrl        mUrl;
         Method      mMethod;
 

src/server/qgsserverresponse.h

@@ -26,12 +26,12 @@
  * \ingroup server
  * QgsServerResponse
  * Class defining response interface passed to services QgsService::executeRequest() method
- *
- *  Note:
- *  This class is intended to be used from python code: method signatures and return types should be 
- *  compatible with pyQGIS/pyQT types and rules.
- *
  */
+
+ // Note:
+ // This class is intended to be used from python code: method signatures and return types should be 
+ // compatible with pyQGIS/pyQT types and rules.
+
 class SERVER_EXPORT QgsServerResponse
 {
     public:
@@ -42,38 +42,61 @@ class SERVER_EXPORT QgsServerResponse
         //! destructor
         virtual ~QgsServerResponse();
 
-       /** Set header entry 
-        *  Add header entry to the response 
-        *  Note that it is usually an error to set hedaer after writng data
+       /** Set Header entry 
+        *  Add Header entry to the response 
+        *  Note that it is usually an error to set Header after writng data
         */
         virtual void setHeader( const QString& key, const QString& value ) = 0;
 
-       /** Set the http return code 
+       /** Set the http return code
+        * @param code HTTP return code value
         */
         virtual void setReturnCode( int code ) = 0;
 
         /**
-         * Send error 
+         * Send error
+         * This method delegate error handling at the server level. This is different
+         * from calling setReturnCodei() along with and a specific response body.
+         * @param code HHTP return code value
+         * @param message An informative error message
          */
         virtual void sendError( int code,  const QString& message ) = 0;
 
         /**
-         * Write string 
-         * @param data string to write
+         * Write string
+         * This is a convenient method that will write directly
+         * to the underlying I/O device
          */
         virtual void write( const QString& data );
 
        /**
         * Write chunk af data
-        * They are convenience method that will write directly to the 
-        * underlying I/O device
+        * This is a convenient method that will write directly
+        * to the underlying I/O device
+        * @creturn the number of bytes that were actually written
         */
         virtual qint64 write( const QByteArray &byteArray );
 
-        // Not exposed in python
+       /**
+        * Writes at most maxSize bytes of data
+        *
+        * This is a convenient method that will write directly
+        * to the underlying I/O device
+        * @return the number of bytes written
+        *
+        *  @note not available in pything bindings
+        */
         virtual qint64 write( const char* data, qint64 maxsize);
 
-        // Not exposed in python
+       /**
+        * Writes at most maxSize bytes of data
+        *
+        * This is a convenient method that will write directly
+        * to the underlying I/O device
+        * @return the number of bytes written
+        *
+        * @note not available in pything bindings
+        */
         virtual qint64 write( const char* data );
 
         /**

src/server/qgsservice.h

@@ -47,8 +47,6 @@ class SERVER_EXPORT QgsService
     /**
      * Return true if the given method is supported for that
      * service.
-     * @param method QGSMethodType the 
-     * @return QString containing the configuration file path
      */
     virtual bool allowMethod( QgsServerRequest::Method ) const = 0;
 

src/server/qgsserviceloader.h

@@ -33,7 +33,8 @@ class SERVER_EXPORT QgsServiceLoader
 {
   public:
 
-    //! Constructor (required by SIP bindings ???)
+    //! Constructor
+    // XXX if not defined then dynamic linker complains about missing symbol
     QgsServiceLoader();
 
     //! Destructor