Revision 32:7b9919d59194, committed 2014-10-11

Comitter:

WiredHome

Date:

Sat Oct 11 17:26:04 2014 +0000

Parent:

31:96da7c08b5d0

Child:

33:d4d1475bafc0

Commit message:

Documentation updates only.

Changed in this revision

--- a/HTTPClient.h	Sat Jul 26 19:47:36 2014 +0000
+++ b/HTTPClient.h	Sat Oct 11 17:26:04 2014 +0000
@@ -63,8 +63,8 @@
     /**
     Provides a basic authentification feature (Base64 encoded username and password)
     Pass two NULL pointers to switch back to no authentication
-    @param user username to use for authentication, must remain valid durlng the whole HTTP session
-    @param user password to use for authentication, must remain valid durlng the whole HTTP session
+    @param[in] user username to use for authentication, must remain valid durlng the whole HTTP session
+    @param[in] user password to use for authentication, must remain valid durlng the whole HTTP session
     */
     void basicAuth(const char* user, const char* password); //Basic Authentification
 
@@ -87,17 +87,17 @@
         http.customHeaders(hdrs, 5);
     @endcode
     
-    @param headers an array (size multiple of two) key-value pairs, must remain valid during the whole HTTP session
-    @param pairs number of key-value pairs
+    @param[in] headers an array (size multiple of two) key-value pairs, must remain valid during the whole HTTP session
+    @param[in] pairs number of key-value pairs
     */
     void customHeaders(const char** headers, size_t pairs);
 
     //High Level setup functions
     /** Execute a GET request on the URL
     Blocks until completion
-    @param url : url on which to execute the request
-    @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
-    @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
+    @param[in] url : url on which to execute the request
+    @param[in,out] pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
+    @param[in] timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
     @return 0 on success, HTTP error (<0) on failure
     */
     HTTPResult get(const char* url, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
@@ -105,39 +105,39 @@
     /** Execute a GET request on the URL
     Blocks until completion
     This is a helper to directly get a piece of text from a HTTP result
-    @param url : url on which to execute the request
-    @param result : pointer to a char array in which the result will be stored
-    @param maxResultLen : length of the char array (including space for the NULL-terminating char)
-    @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
+    @param[in] url : url on which to execute the request
+    @param[out] result : pointer to a char array in which the result will be stored
+    @param[in] maxResultLen : length of the char array (including space for the NULL-terminating char)
+    @param[in] timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
     @return 0 on success, HTTP error (<0) on failure
     */
     HTTPResult get(const char* url, char* result, size_t maxResultLen, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
 
     /** Execute a POST request on the URL
     Blocks until completion
-    @param url : url on which to execute the request
-    @param dataOut : a IHTTPDataOut instance that contains the data that will be posted
-    @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
-    @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
+    @param[in] url : url on which to execute the request
+    @param[out] dataOut : a IHTTPDataOut instance that contains the data that will be posted
+    @param[in,out] pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
+    @param[in] timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
     @return 0 on success, HTTP error (<0) on failure
     */
     HTTPResult post(const char* url, const IHTTPDataOut& dataOut, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
 
     /** Execute a PUT request on the URL
     Blocks until completion
-    @param url : url on which to execute the request
-    @param dataOut : a IHTTPDataOut instance that contains the data that will be put
-    @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
-    @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
+    @param[in] url : url on which to execute the request
+    @param[in] dataOut : a IHTTPDataOut instance that contains the data that will be put
+    @param[in,out] pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
+    @param[in] timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
     @return 0 on success, HTTP error (<0) on failure
     */
     HTTPResult put(const char* url, const IHTTPDataOut& dataOut, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
 
     /** Execute a DELETE request on the URL
     Blocks until completion
-    @param url : url on which to execute the request
-    @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
-    @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
+    @param[in] url : url on which to execute the request
+    @param[in,out] pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
+    @param[in] timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
     @return 0 on success, HTTP error (<0) on failure
     */
     HTTPResult del(const char* url, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
@@ -148,7 +148,7 @@
     int getHTTPResponseCode();
 
     /** Set the maximum number of automated redirections
-    @param i is the number of redirections. Values < 1 are
+    @param[in] i is the number of redirections. Values < 1 are
         set to 1.
     */
     void setMaxRedirections(int i = 1);

--- a/IHTTPData.h	Sat Jul 26 19:47:36 2014 +0000
+++ b/IHTTPData.h	Sat Oct 11 17:26:04 2014 +0000
@@ -36,14 +36,15 @@
   virtual void readReset() = 0;
 
   /** Read a piece of data to be transmitted
-   * @param buf Pointer to the buffer on which to copy the data
-   * @param len Length of the buffer
-   * @param pReadLen Pointer to the variable on which the actual copied data length will be stored
+   * @param[out] buf Pointer to the buffer on which to copy the data
+   * @param[in] len Length of the buffer
+   * @param[out] pReadLen Pointer to the variable on which the actual copied data length will be stored
    */
   virtual int read(char* buf, size_t len, size_t* pReadLen) = 0;
   
   /** Get MIME type
-   * @param type Internet media type from Content-Type header
+   * @param[out] type Internet media type from Content-Type header
+   * @param[in] maxTypeLen is the size of the type buffer to write to
    */
   virtual int getDataType(char* type, size_t maxTypeLen) = 0; //Internet media type for Content-Type header
   

--- a/data/HTTPFile.h	Sat Jul 26 19:47:36 2014 +0000
+++ b/data/HTTPFile.h	Sat Oct 11 17:26:04 2014 +0000
@@ -24,23 +24,26 @@
         virtual void writeReset();
         
         /** Write a piece of data transmitted by the server
-        * @param buf Pointer to the buffer from which to copy the data
-        * @param len Length of the buffer
+        * @param[in] buf Pointer to the buffer from which to copy the data
+        * @param[in] len Length of the buffer
+        * @returns number of bytes written.
         */
         virtual int write(const char* buf, size_t len);
         
         /** Set MIME type
-        * @param type Internet media type from Content-Type header
+        * @param[in] type Internet media type from Content-Type header
         */
         virtual void setDataType(const char* type);
         
         /** Determine whether the data is chunked
         *  Recovered from Transfer-Encoding header
+        * @param[in] chunked indicates the transfer is chunked.
         */
         virtual void setIsChunked(bool chunked);
         
         /** If the data is not chunked, set its size
         * From Content-Length header
+        * @param[in] len defines the size of the non-chunked transfer.
         */
         virtual void setDataLen(size_t len);
     private:

--- a/data/HTTPMap.h	Sat Jul 26 19:47:36 2014 +0000
+++ b/data/HTTPMap.h	Sat Oct 11 17:26:04 2014 +0000
@@ -39,8 +39,8 @@
 
   /** Put Key/Value pair
    The references to the parameters must remain valid as long as the clear() function is not called
-   @param key The key to use
-   @param value The corresponding value
+   @param[in] key The key to use
+   @param[in] value The corresponding value
    */
   void put(const char* key, const char* value);
 

--- a/data/HTTPText.h	Sat Jul 26 19:47:36 2014 +0000
+++ b/data/HTTPText.h	Sat Oct 11 17:26:04 2014 +0000
@@ -29,13 +29,13 @@
 {
 public:
   /** Create an HTTPText instance for output
-   * @param str String to be transmitted
+   * @param[in] str String to be transmitted
    */
   HTTPText(char* str);
 
   /** Create an HTTPText instance for input
-   * @param str Buffer to store the incoming string
-   * @param size Size of the buffer
+   * @param[in] str Buffer to store the incoming string
+   * @param[in] size Size of the buffer
    */
   HTTPText(char* str, size_t size);