docs: document event & http loop

include/http/req.h

@@ -12,7 +12,7 @@
 #define HTTP_MAX_ALLOWED_HEADERS 16
 #define HTTP_MAX_REGEX_GROUPS 4
 
-/*
+/**
  * Struct representing the specific type of request
  */
 typedef struct http_request {
@@ -29,6 +29,9 @@ typedef struct http_request {
   size_t num_headers;
 } http_request;
 
+/**
+ * Result of the HTTP parse function
+ */
 typedef enum http_parse_error {
   http_parse_error_ok = 0,
   http_parse_error_incomplete = 1,

include/http/res.h

@@ -6,12 +6,18 @@
 
 #include "http/types.h"
 
+/**
+ * Struct describing a header for the response.
+ */
 typedef struct http_response_header {
   http_header type;
   const char *value;
   bool owned;
 } http_response_header;
 
+/**
+ * Struct representing an HTTP response.
+ */
 typedef struct http_response {
   http_status status;
   const char *head;
@@ -22,26 +28,41 @@ typedef struct http_response {
   size_t header_count;
 } http_response;
 
-/*
- * Set the request body to the given buffer. If owned is set to true, the body
- * buffer will be free'd after the request has finished.
+/**
+ * Set the request body to the given buffer.
+ *
+ * @param res response to modify
+ * @param body pointer to the buf containing the body
+ * @param body_len length of the body
+ * @owned whether the body should be freed after processing the request
  */
 void http_res_set_body_buf(http_response *res, const char *body,
                            size_t body_len, bool owned);
 
-/*
+/**
  * Set the request body to the given filename.
+ *
+ * @param res response to modify
+ * @param filename path to the file to return
  */
 void http_res_set_body_file(http_response *res, const char *filename);
 
-/*
+/**
  * Add a header to the response.
+ *
+ * @param res response to modify
+ * @param type type of the header
+ * @param value value of the header
+ * @param owned whether the value should be freed after processing the request
  */
 void http_res_add_header(http_response *res, http_header type,
                          const char *value, bool owned);
 
-/*
+/**
  * Add a Content-Type header corresponding to the mime type.
+ *
+ * @param res response to modiy
+ * @param mime_type mime type of the response
  */
 void http_res_set_mime_type(http_response *res, http_mime_type mime_type);
 

include/http/types.h

@@ -147,10 +147,25 @@ typedef struct http_body {
   size_t len;
 } http_body;
 
+/**
+ * Initialize a new body struct.
+ *
+ * @return pointer to the newly allocated object.
+ */
 http_body *http_body_init();
 
+/**
+ * Reset a body, allowing it to be reused as if newly allocated.
+ *
+ * @param body body to reset
+ */
 void http_body_reset(http_body *body);
 
+/**
+ * Free a body. Internally, this calls http_body_reset.
+ *
+ * @param body body to free
+ */
 void http_body_free(http_body *body);
 
 #endif