Advanced the documentation

include/yukihttp/request.hpp

@@ -9,39 +9,105 @@
 namespace yuki::http
 {
 
+/**
+* @brief Upload/Download progress callback.
+*
+* Defines the signature of a callback usable as a progress callback.
+* The argument are in order :
+* \li The number of bytes already downloaded
+* \li The expected number of bytes to download
+* \li The number of bytes already upload
+* \li The expected number of bytes to upload
+*/
 using progress_callback = std::function<void(long, long, long, long)>;
 
+/**
+* @brief Alias for headers structure
+*
+*/
 using headers_t = std::map<std::string, std::string>;
 
 class mime;
 
+
+/**
+* @brief A HTTP(s) response
+*
+* \todo Fix error reporting. Separate cURL error to HTTP errors
+*/
 struct response
 {
+	/*! Return code of the response. 200 if no error, -1 for cURL related errors */
 	int code = 0;
+
+	/*! Body of the HTTP response */
 	std::string body = "";
+
+	/*! Headers of the HTTP response  */
 	yuki::http::headers_t headers;
 };
 
 
+/**
+* @brief HTTP(S) request
+*
+* Class used to perform HTTP(S) requests via cURL. Meant to be used as a REST client it only provides the following requests :
+* \li GET
+* \li HEAD
+* \li DELETE
+* \li POST
+*
+*/
 class request
 {
 public:
+
+	/**
+	*
+	* @param url : URL on which the request should be performed.
+	*/
 	explicit request(const std::string & url);
+
 	~request();
 
 	request(const request&) = delete;
 	request& operator=(const request&) = delete;
 	request(request&&) = default;
 	request& operator=(request && ) = default;
 
+	/**
+	* @brief Enable or disable verbose mode.
+	*
+	* If verbose mode is enabled, debug information provided by cURL will be written on the stream provided to set_verbose_output(std::ostream & out) const.
+	* If set_verbose_output(std::ostream & out) const isn't called, then the output is printed to stdcerr instead.
+	*
+	* @param is_verbose : true if verbose mode should be enable, false if not.
+	*/
 	void set_verbose(bool is_verbose) const;
+
+	/**
+	* @brief Set up the verbose output stream.
+	* 
+	* @param out : Stream to use for verbose output. 
+	*/
 	void set_verbose_output(std::ostream & out) const;
 
 	void enable_progress_meter(bool is_enabled) const;
 	void set_progress_callback(yuki::http::progress_callback & callback) const;
 
+
+	/**
+	* @brief Set the timeout for request.
+	* 
+	* @param ms : Timeout duration in milliseconds.
+	*/
 	void set_timeout(unsigned int ms) const;
 
+	/**
+	* @brief Set the user agent used for the request.
+	* 
+	* @param ua : User agent to use.
+	*/
 	void set_user_agent(const std::string & ua) const;
 
 	void set_auth_username(const std::string & username) const;

src/request.cpp

@@ -198,10 +198,10 @@ yuki::http::response yuki::http::request::execute_request() const
 
 	yuki::http::response rep;
 
-	curl_easy_setopt(m_handle, CURLOPT_WRITEFUNCTION, write_callback);
+	curl_easy_setopt(m_handle, CURLOPT_WRITEFUNCTION, yuki::http::callbacks::write_callback);
 	curl_easy_setopt(m_handle, CURLOPT_WRITEDATA, &rep);
 
-	curl_easy_setopt(m_handle, CURLOPT_HEADERFUNCTION, header_callback);
+	curl_easy_setopt(m_handle, CURLOPT_HEADERFUNCTION, yuki::http::callbacks::header_callback);
 	curl_easy_setopt(m_handle, CURLOPT_HEADERDATA, &rep);
 
 

src/utils.hpp

@@ -2,26 +2,45 @@
 
 #include <cstddef>
 
+
 /**
-* @brief ...
+* @brief Namespace used to define callbacks used internaly bu cURL
 * 
-* @param data p_data:...
-* @param size p_size:...
-* @param data_size p_data_size:...
-* @param user_data p_user_data:...
-* @return std::size_t
+*/
+namespace yuki::http::callbacks
+{
+
+/**
+* @brief Function passed as callback to cURL to receive data.
+*
+* This function receive data from cURL and fills a yuki::http::response object with it.
+*
+* @warning Headers are received via the header_callback(void *data, std::size_t size, std::size_t data_size, void *user_data) function.
+*
+* @param data p_data: Data to write into the response.
+* @param size p_size: Unused. cURL always set it to 1
+* @param data_size p_data_size: Data size in bytes.
+* @param user_data p_user_data: Pointer to the object that will receive the data. \a must be pointing to a yuki::http::response object.
+* @return std::size_t : Number of bytes read or 0 in case of error.
 */
 std::size_t write_callback(void *data, std::size_t size, std::size_t data_size, void *user_data);
 
 
 
 /**
-* @brief ...
-* 
-* @param data p_data:...
-* @param size p_size:...
-* @param data_size p_data_size:...
-* @param user_data p_user_data:...
-* @return std::size_t
+* @brief Function passed as callback to cURL to receive headers.
+*
+* This function receive headers from cURL and fills a yuki::http::response object with it.
+* It processes a single header line and is called by cURL as many time as needed.
+*
+* @warning data is received via the write_callback(void *data, std::size_t size, std::size_t data_size, void *user_data) function.
+*
+* @param data p_data: Header line in the forme of key:value or key.
+* @param size p_size: Size of an element in bytes.
+* @param data_size p_data_size: Number of elements.
+* @param user_data p_user_data: Pointer to the object to which append the header. \a must be pointing to a yuki::http::response object.
+* @return std::size_t : \a Must always return 0.
 */
 std::size_t header_callback(void *data, std::size_t size, std::size_t data_size, void *user_data);
+
+}