Documentation cleanup. [ci skip]

include/sagui.h

@@ -124,8 +124,8 @@ typedef void (*sg_free_cb)(void *handle);
  * Callback signature used by functions that save streams.
  * \param[out] handle Stream handle.
  * \param[out] overwritten Overwrite an already existed stream.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to abort the saving.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to abort the saving.
  */
 typedef int (*sg_save_cb)(void *handle, bool overwritten);
 
@@ -134,8 +134,8 @@ typedef int (*sg_save_cb)(void *handle, bool overwritten);
  * \param[out] handle Stream handle.
  * \param[out] path Absolute path to store the stream.
  * \param[out] overwritten Overwrite an already existed stream.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to abort the saving.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to abort the saving.
  */
 typedef int (*sg_save_as_cb)(void *handle, const char *path, bool overwritten);
 
@@ -188,7 +188,7 @@ SG_EXTERN char *sg_strerror(int errnum, char *errmsg, size_t errlen);
 /**
  * Checks if a string is a HTTP post method.
  * \param[in] method Null-terminated string.
- * \return `true` if \pr{method} is `POST`, `PUT`, `DELETE` or `OPTIONS`.
+ * \retval true If \pr{method} is `POST`, `PUT`, `DELETE` or `OPTIONS`.
  */
 SG_EXTERN bool sg_is_post(const char *method);
 
@@ -242,8 +242,8 @@ SG_EXTERN void sg_str_free(struct sg_str *str);
  * \param[in] str String handle.
  * \param[in] val String to be written.
  * \param[in] len Length of the string to be written.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_str_write(struct sg_str *str, const char *val, size_t len);
 
@@ -254,8 +254,8 @@ SG_EXTERN int sg_str_write(struct sg_str *str, const char *val, size_t len);
  *  specification).
  * \param[in] ap Arguments list (handled by
  *  [`va_start()`](https://linux.die.net/man/3/va_start)/[`va_end()`](https://linux.die.net/man/3/va_end)).
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_str_printf_va(struct sg_str *str, const char *fmt, va_list ap);
 
@@ -266,8 +266,8 @@ SG_EXTERN int sg_str_printf_va(struct sg_str *str, const char *fmt, va_list ap);
  *  specification).
  * \param[in] ... Additional arguments (following the same [`printf()`](https://linux.die.net/man/3/printf) arguments
  *  specification).
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_str_printf(struct sg_str *str, const char *fmt, ...)
 __SG_FORMAT(2, 3);
@@ -284,15 +284,15 @@ SG_EXTERN const char *sg_str_content(struct sg_str *str);
  * Returns the total string length from the handle \pr{str}.
  * \param[in] str String handle.
  * \return Total string length.
- * \retval EINVAL - Invalid argument.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN size_t sg_str_length(struct sg_str *str);
 
 /**
  * Cleans all existing content in the string handle \pr{str}.
  * \param[in] str String handle.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_str_clear(struct sg_str *str);
 
@@ -316,8 +316,8 @@ struct sg_strmap;
  * Callback signature used by #sg_strmap_iter() to iterate pairs of strings.
  * \param[out] cls User-defined closure.
  * \param[out] pair Current iterated pair.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to stop pairs iteration.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to stop pairs iteration.
  */
 typedef int (*sg_strmap_iter_cb)(void *cls, struct sg_strmap *pair);
 
@@ -326,9 +326,9 @@ typedef int (*sg_strmap_iter_cb)(void *cls, struct sg_strmap *pair);
  * \param[out] cls User-defined closure.
  * \param[out] pair_a Current left pair (A).
  * \param[out] pair_b Current right pair (B).
- * \retval -1 - A < B.
- * \retval 0 - A == B.
- * \retval 1 - A > B.
+ * \retval -1 A < B.
+ * \retval 0 A == B.
+ * \retval 1 A > B.
  */
 typedef int (*sg_strmap_sort_cb)(void *cls, struct sg_strmap *pair_a, struct sg_strmap *pair_b);
 
@@ -353,8 +353,8 @@ SG_EXTERN const char *sg_strmap_val(struct sg_strmap *pair);
  * \param[in,out] map Pairs map pointer to add a new pair.
  * \param[in] name Pair name.
  * \param[in] val Pair value.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  * \note It cannot check if a name already exists in a pair added to the \pr{map}, then the uniqueness must be managed
  * by the application.
  * \warning It exits the application if called when no memory space is available.
@@ -366,8 +366,8 @@ SG_EXTERN int sg_strmap_add(struct sg_strmap **map, const char *name, const char
  * \param[in,out] map Pairs map pointer to set a new pair.
  * \param[in] name Pair name.
  * \param[in] val Pair value.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  * \note If a name already exists in a pair previously added into the \pr{map}, then the function replaces its value,
  * otherwise it is added as a new pair.
  * \warning It exits the application if called when no memory space is available.
@@ -379,9 +379,9 @@ SG_EXTERN int sg_strmap_set(struct sg_strmap **map, const char *name, const char
  * \param[in] map Pairs map.
  * \param[in] name Name to find the pair.
  * \param[in,out] pair Pointer of the variable to store the found pair.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval ENOENT - Pair not found.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval ENOENT Pair not found.
  */
 SG_EXTERN int sg_strmap_find(struct sg_strmap *map, const char *name, struct sg_strmap **pair);
 
@@ -398,9 +398,9 @@ SG_EXTERN const char *sg_strmap_get(struct sg_strmap *map, const char *name);
  * Removes a pair by name.
  * \param[in] map Pointer to the pairs map.
  * \param[in] name Name to find and then remove the pair.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval ENOENT - Pair already removed.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval ENOENT Pair already removed.
  */
 SG_EXTERN int sg_strmap_rm(struct sg_strmap **map, const char *name);
 
@@ -409,8 +409,8 @@ SG_EXTERN int sg_strmap_rm(struct sg_strmap **map, const char *name);
  * \param[in] map Pairs map.
  * \param[in] cb Callback to iterate the pairs.
  * \param[in,out] cls User-specified value.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  * \return Callback result when it is different from `0`.
  */
 SG_EXTERN int sg_strmap_iter(struct sg_strmap *map, sg_strmap_iter_cb cb, void *cls);
@@ -420,8 +420,8 @@ SG_EXTERN int sg_strmap_iter(struct sg_strmap *map, sg_strmap_iter_cb cb, void *
  * \param[in,out] map Pointer to the pairs map.
  * \param[in] cb Callback to sort the pairs.
  * \param[in,out] cls User-specified value.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_strmap_sort(struct sg_strmap **map, sg_strmap_sort_cb cb, void *cls);
 
@@ -436,8 +436,8 @@ SG_EXTERN unsigned int sg_strmap_count(struct sg_strmap *map);
 /**
  * Returns the next pair in the map.
  * \param[in,out] next Pointer to the next pair.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_strmap_next(struct sg_strmap **next);
 
@@ -507,8 +507,8 @@ typedef bool (*sg_httpauth_cb)(void *cls, struct sg_httpauth *auth, struct sg_ht
  * \param[out] name Uploaded file name.
  * \param[out] mime Uploaded file content-type (e.g.: `text/plain`, `image/png`, `application/json` etc.).
  * \param[out] encoding Uploaded file transfer-encoding (e.g.: `chunked`, `deflate`, `gzip` etc.).
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to refuse the upload.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to refuse the upload.
  */
 typedef int (*sg_httpupld_cb)(void *cls, void **handle, const char *dir, const char *field, const char *name,
                               const char *mime, const char *encoding);
@@ -517,8 +517,8 @@ typedef int (*sg_httpupld_cb)(void *cls, void **handle, const char *dir, const c
  * Callback signature used to iterate uploaded files.
  * \param[out] cls User-defined closure.
  * \param[out] upld Current upload item.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to stop list iteration.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to stop list iteration.
  */
 typedef int (*sg_httpuplds_iter_cb)(void *cls, struct sg_httpupld *upld);
 
@@ -534,9 +534,9 @@ typedef void (*sg_httpreq_cb)(void *cls, struct sg_httpreq *req, struct sg_httpr
  * Sets the authentication protection space (realm).
  * \param[in] auth Authentication handle.
  * \param[in] realm Realm string.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Realm already set.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Realm already set.
  * \warning It exits the application if called when no memory space is available.
  */
 SG_EXTERN int sg_httpauth_set_realm(struct sg_httpauth *auth, const char *realm);
@@ -554,17 +554,17 @@ SG_EXTERN const char *sg_httpauth_realm(struct sg_httpauth *auth);
  * \param[in] auth Authentication handle.
  * \param[in] justification Justification message.
  * \param[in] content_type `Content-Type` of the justification.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Already denied.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Already denied.
  */
 SG_EXTERN int sg_httpauth_deny(struct sg_httpauth *auth, const char *justification, const char *content_type);
 
 /**
  * Cancels the authentication loop while the user is trying to acess the server.
  * \param[in] auth Authentication handle.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpauth_cancel(struct sg_httpauth *auth);
 
@@ -589,17 +589,17 @@ SG_EXTERN const char *sg_httpauth_pwd(struct sg_httpauth *auth);
  * \param[in] uplds Uploads list handle.
  * \param[in] cb Callback to iterate over upload items.
  * \param[in] cls User-defined closure.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval E<ERROR> - User-defined error to abort the list iteration.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval E<ERROR> User-defined error to abort the list iteration.
  */
 SG_EXTERN int sg_httpuplds_iter(struct sg_httpupld *uplds, sg_httpuplds_iter_cb cb, void *cls);
 
 /**
  * Gets the next upload item starting from the first item pointer \pr{upld}.
  * \param[in,out] upld Next upload item starting from the first item pointer.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpuplds_next(struct sg_httpupld **upld);
 
@@ -670,10 +670,10 @@ SG_EXTERN uint64_t sg_httpupld_size(struct sg_httpupld *upld);
  * Saves the uploaded file defining the destination path by upload name and directory.
  * \param[in] upld Upload handle.
  * \param[in] overwritten Overwrite upload file if it exists.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EEXIST - File already exists (if \pr{overwritten} is `false`).
- * \retval EISDIR - Destination file is a directory.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EEXIST File already exists (if \pr{overwritten} is `false`).
+ * \retval EISDIR Destination file is a directory.
  */
 SG_EXTERN int sg_httpupld_save(struct sg_httpupld *upld, bool overwritten);
 
@@ -682,10 +682,10 @@ SG_EXTERN int sg_httpupld_save(struct sg_httpupld *upld, bool overwritten);
  * \param[in] upld Upload handle.
  * \param[in] path Absolute destination path.
  * \param[in] overwritten Overwrite upload file if it exists.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EEXIST - File already exists (if \pr{overwritten} is `true`).
- * \retval EISDIR - Destination file is a directory.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EEXIST File already exists (if \pr{overwritten} is `true`).
+ * \retval EISDIR Destination file is a directory.
  */
 SG_EXTERN int sg_httpupld_save_as(struct sg_httpupld *upld, const char *path, bool overwritten);
 
@@ -761,7 +761,7 @@ SG_EXTERN struct sg_str *sg_httpreq_payload(struct sg_httpreq *req);
 /**
  * Checks if the client is uploading data.
  * \param[in] req Request handle.
- * \return `true` if the client is uploading data, `false` otherwise. If \pr{req} is null, sets the `errno` to `EINVAL`.
+ * \retval true If the client is uploading data, `false` otherwise. If \pr{req} is null, sets the `errno` to `EINVAL`.
  */
 SG_EXTERN bool sg_httpreq_is_uploading(struct sg_httpreq *req);
 
@@ -779,8 +779,8 @@ SG_EXTERN struct sg_httpupld *sg_httpreq_uploads(struct sg_httpreq *req);
 /**
  * Returns the GnuTLS session handle.
  * \param[in] req Request handle.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN void *sg_httpreq_tls_session(struct sg_httpreq *req);
 
@@ -790,8 +790,8 @@ SG_EXTERN void *sg_httpreq_tls_session(struct sg_httpreq *req);
  * Sets user data to the request handle.
  * \param[in] req Request handle.
  * \param[in] data User data pointer.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpreq_set_user_data(struct sg_httpreq *req, void *data);
 
@@ -817,8 +817,8 @@ SG_EXTERN struct sg_strmap **sg_httpres_headers(struct sg_httpres *res);
  * \param[in] res Response handle.
  * \param[in] name Cookie name.
  * \param[in] val Cookie value.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  * \warning It exits the application if called when no memory space is available.
  */
 SG_EXTERN int sg_httpres_set_cookie(struct sg_httpres *res, const char *name, const char *val);
@@ -829,9 +829,9 @@ SG_EXTERN int sg_httpres_set_cookie(struct sg_httpres *res, const char *name, co
  * \param[in] val Null-terminated string.
  * \param[in] content_type `Content-Type` of the content.
  * \param[in] status HTTP status code.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Operation already in progress.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Operation already in progress.
  * \warning It exits the application if called when no memory space is available.
  */
 #define sg_httpres_send(res, val, content_type, status) \
@@ -844,9 +844,9 @@ SG_EXTERN int sg_httpres_set_cookie(struct sg_httpres *res, const char *name, co
  * \param[in] size Content size.
  * \param[in] content_type `Content-Type` of the content.
  * \param[in] status HTTP status code.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Operation already in progress.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Operation already in progress.
  * \warning It exits the application if called when no memory space is available.
  */
 SG_EXTERN int sg_httpres_sendbinary(struct sg_httpres *res, void *buf, size_t size, const char *content_type,
@@ -857,11 +857,11 @@ SG_EXTERN int sg_httpres_sendbinary(struct sg_httpres *res, void *buf, size_t si
  * \param[in] res Response handle.
  * \param[in] filename Path of the file to be sent.
  * \param[in] status HTTP status code.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Operation already in progress.
- * \retval EISDIR - Is a directory.
- * \retval EBADF - Bad file number.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Operation already in progress.
+ * \retval EISDIR Is a directory.
+ * \retval EBADF Bad file number.
  * \warning It exits the application if called when no memory space is available.
  */
 #define sg_httpres_download(res, filename, status) \
@@ -872,11 +872,11 @@ SG_EXTERN int sg_httpres_sendbinary(struct sg_httpres *res, void *buf, size_t si
  * \param[in] res Response handle.
  * \param[in] filename Path of the file to be sent.
  * \param[in] status HTTP status code.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Operation already in progress.
- * \retval EISDIR - Is a directory.
- * \retval EBADF - Bad file number.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Operation already in progress.
+ * \retval EISDIR Is a directory.
+ * \retval EBADF Bad file number.
  * \warning It exits the application if called when no memory space is available.
  */
 #define sg_httpres_render(res, filename, status) \
@@ -891,12 +891,12 @@ SG_EXTERN int sg_httpres_sendbinary(struct sg_httpres *res, void *buf, size_t si
  * \param[in] filename Path of the file to be sent.
  * \param[in] rendered If `true` the file is rendered, otherwise downloaded.
  * \param[in] status HTTP status code.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Operation already in progress.
- * \retval EISDIR - Is a directory.
- * \retval EBADF - Bad file number.
- * \retval EFBIG - File too large.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Operation already in progress.
+ * \retval EISDIR Is a directory.
+ * \retval EBADF Bad file number.
+ * \retval EFBIG File too large.
  * \warning It exits the application if called when no memory space is available.
  */
 SG_EXTERN int sg_httpres_sendfile(struct sg_httpres *res, uint64_t size, uint64_t max_size, uint64_t offset,
@@ -911,9 +911,9 @@ SG_EXTERN int sg_httpres_sendfile(struct sg_httpres *res, uint64_t size, uint64_
  * \param[in] handle Stream handle.
  * \param[in] free_cb Callback to free the stream handle.
  * \param[in] status HTTP status code.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Operation already in progress.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Operation already in progress.
  * \note Use `size = 0` if the stream size is unknown.
  * \warning It exits the application if called when no memory space is available.
  */
@@ -929,11 +929,11 @@ SG_EXTERN int sg_httpres_sendstream(struct sg_httpres *res, uint64_t size, size_
  * \param[in] val Null-terminated string.
  * \param[in] content_type `Content-Type` of the content.
  * \param[in] status HTTP status code.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval ENOMEM - Out of memory.
- * \retval ENOBUFS - No buffer space available.
- * \retval EALREADY - Operation already in progress.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval ENOMEM Out of memory.
+ * \retval ENOBUFS No buffer space available.
+ * \retval EALREADY Operation already in progress.
  * \note When compression succeeds, the header `Content-Encoding: deflate` is automatically added to the response.
  * \warning It exits the application if called when no memory space is available.
  */
@@ -948,11 +948,11 @@ SG_EXTERN int sg_httpres_sendstream(struct sg_httpres *res, uint64_t size, size_
  * \param[in] size Content size.
  * \param[in] content_type `Content-Type` of the content.
  * \param[in] status HTTP status code.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval ENOMEM - Out of memory.
- * \retval ENOBUFS - No buffer space available.
- * \retval EALREADY - Operation already in progress.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval ENOMEM Out of memory.
+ * \retval ENOBUFS No buffer space available.
+ * \retval EALREADY Operation already in progress.
  * \note When compression succeeds, the header `Content-Encoding: deflate` is automatically added to the response.
  * \warning It exits the application if called when no memory space is available.
  */
@@ -968,8 +968,8 @@ SG_EXTERN int sg_httpres_zsendstream(struct sg_httpres *res, uint64_t size, sg_r
 /**
  * Clears all headers, cookies, status and internal buffers of the response handle.
  * \param[in] res Response handle.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpres_clear(struct sg_httpres *res);
 
@@ -1016,7 +1016,7 @@ SG_EXTERN void sg_httpsrv_free(struct sg_httpsrv *srv);
  * key exchange.
  * \param[in] port Port for listening to connections.
  * \param[in] threaded Enable/disable the threaded model. If `true`, the server creates one thread per connection.
- * \return `true` if the server is started, `false` otherwise. If \pr{srv} is null, sets the `errno` to `EINVAL`.
+ * \retval true If the server is started, `false` otherwise. If \pr{srv} is null, sets the `errno` to `EINVAL`.
  * \note If port is `0`, the operating system will assign an unused port randomly.
  */
 SG_EXTERN bool sg_httpsrv_tls_listen2(struct sg_httpsrv *srv, const char *key, const char *pwd, const char *cert,
@@ -1029,7 +1029,7 @@ SG_EXTERN bool sg_httpsrv_tls_listen2(struct sg_httpsrv *srv, const char *key, c
  * \param[in] cert Memory pointer for the certificate (cert.pem) to be used by the HTTPS server.
  * \param[in] port Port for listening to connections.
  * \param[in] threaded Enable/disable the threaded model. If `true`, the server creates one thread per connection.
- * \return `true` if the server is started, `false` otherwise. If \pr{srv} is null, sets the `errno` to `EINVAL`.
+ * \retval true If the server is started, `false` otherwise. If \pr{srv} is null, sets the `errno` to `EINVAL`.
  * \note If port is `0`, the operating system will assign an unused port randomly.
  */
 SG_EXTERN bool sg_httpsrv_tls_listen(struct sg_httpsrv *srv, const char *key, const char *cert,
@@ -1042,7 +1042,7 @@ SG_EXTERN bool sg_httpsrv_tls_listen(struct sg_httpsrv *srv, const char *key, co
  * \param[in] srv Server handle.
  * \param[in] port Port for listening to connections.
  * \param[in] threaded Enable/disable the threaded model. If `true`, the server creates one thread per connection.
- * \return `true` if the server is started, `false` otherwise. If \pr{srv} is null, sets the `errno` to `EINVAL`.
+ * \retval true If the server is started, `false` otherwise. If \pr{srv} is null, sets the `errno` to `EINVAL`.
  * \note If port is `0`, the operating system will assign randomly an unused port.
  */
 SG_EXTERN bool sg_httpsrv_listen(struct sg_httpsrv *srv, uint16_t port, bool threaded);
@@ -1050,7 +1050,7 @@ SG_EXTERN bool sg_httpsrv_listen(struct sg_httpsrv *srv, uint16_t port, bool thr
 /**
  * Stops the server not to accept new connections.
  * \param[in] srv Server handle.
- * \return `0` if the server is stopped. If \pr{srv} is null, sets the `errno` to `EINVAL`.
+ * \retval 0 If the server is stopped. If \pr{srv} is null, sets the `errno` to `EINVAL`.
  */
 SG_EXTERN int sg_httpsrv_shutdown(struct sg_httpsrv *srv);
 
@@ -1064,7 +1064,7 @@ SG_EXTERN uint16_t sg_httpsrv_port(struct sg_httpsrv *srv);
 /**
  * Checks if the server was started in threaded model.
  * \param[in] srv Server handle.
- * \return `true` if the server is in threaded model, `false` otherwise. If \pr{srv} is null, sets the `errno` to
+ * \retval true If the server is in threaded model, `false` otherwise. If \pr{srv} is null, sets the `errno` to
  * `EINVAL`.
  */
 SG_EXTERN bool sg_httpsrv_is_threaded(struct sg_httpsrv *srv);
@@ -1078,8 +1078,8 @@ SG_EXTERN bool sg_httpsrv_is_threaded(struct sg_httpsrv *srv);
  * \param[in] free_cb Callback to free stream of the uploaded files.
  * \param[in] save_cb Callback to save the uploaded files.
  * \param[in] save_as_cb Callback to save the uploaded files defining their path.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpsrv_set_upld_cbs(struct sg_httpsrv *srv, sg_httpupld_cb cb, void *cls, sg_write_cb write_cb,
                                       sg_free_cb free_cb, sg_save_cb save_cb, sg_save_as_cb save_as_cb);
@@ -1088,8 +1088,8 @@ SG_EXTERN int sg_httpsrv_set_upld_cbs(struct sg_httpsrv *srv, sg_httpupld_cb cb,
  * Sets the directory to save the uploaded files.
  * \param[in] srv Server handle.
  * \param[in] dir Directory as null-terminated string.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpsrv_set_upld_dir(struct sg_httpsrv *srv, const char *dir);
 
@@ -1105,8 +1105,8 @@ SG_EXTERN const char *sg_httpsrv_upld_dir(struct sg_httpsrv *srv);
  * Sets a size to the post buffering.
  * \param[in] srv Server handle.
  * \param[in] size Post buffering size.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpsrv_set_post_buf_size(struct sg_httpsrv *srv, size_t size);
 
@@ -1122,8 +1122,8 @@ SG_EXTERN size_t sg_httpsrv_post_buf_size(struct sg_httpsrv *srv);
  * Sets a limit to the total payload.
  * \param[in] srv Server handle.
  * \param[in] limit Payload total limit. Use zero for no limit.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpsrv_set_payld_limit(struct sg_httpsrv *srv, size_t limit);
 
@@ -1139,8 +1139,8 @@ SG_EXTERN size_t sg_httpsrv_payld_limit(struct sg_httpsrv *srv);
  * Sets a limit to the total uploads.
  * \param[in] srv Server handle.
  * \param[in] limit Uploads total limit. Use zero for no limit.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpsrv_set_uplds_limit(struct sg_httpsrv *srv, uint64_t limit);
 
@@ -1156,8 +1156,8 @@ SG_EXTERN uint64_t sg_httpsrv_uplds_limit(struct sg_httpsrv *srv);
  * Sets the size for the thread pool.
  * \param[in] srv Server handle.
  * \param[in] size Thread pool size. Size greater than 1 enables the thread pooling.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpsrv_set_thr_pool_size(struct sg_httpsrv *srv, unsigned int size);
 
@@ -1173,8 +1173,8 @@ SG_EXTERN unsigned int sg_httpsrv_thr_pool_size(struct sg_httpsrv *srv);
  * Sets the inactivity time to a client get time out.
  * \param[in] srv Server handle.
  * \param[in] timeout Timeout (in seconds). Use zero for infinity timeout.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpsrv_set_con_timeout(struct sg_httpsrv *srv, unsigned int timeout);
 
@@ -1190,8 +1190,8 @@ SG_EXTERN unsigned int sg_httpsrv_con_timeout(struct sg_httpsrv *srv);
  * Sets the limit of concurrent connections.
  * \param[in] srv Server handle.
  * \param[in] limit Concurrent connections limit. Use zero for no limit.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_httpsrv_set_con_limit(struct sg_httpsrv *srv, unsigned int limit);
 
@@ -1240,8 +1240,8 @@ SG_EXTERN const char *sg_entrypoint_name(struct sg_entrypoint *entrypoint);
  * Sets user data to the entry-point handle.
  * \param[in] entrypoint Entry-point handle.
  * \param[in] data User data pointer.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_entrypoint_set_user_data(struct sg_entrypoint *entrypoint, void *data);
 
@@ -1263,8 +1263,8 @@ struct sg_entrypoints;
  * Callback signature used by #sg_entrypoints_iter() to iterate entry-point items.
  * \param[out] cls User-defined closure.
  * \param[out] pair Current iterated entry-point.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to stop the items iteration.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to stop the items iteration.
  */
 typedef int (*sg_entrypoints_iter_cb)(void *cls, struct sg_entrypoint *entrypoint);
 
@@ -1287,9 +1287,9 @@ SG_EXTERN void sg_entrypoints_free(struct sg_entrypoints *entrypoints);
  * \param[in] entrypoints Entry-points handle.
  * \param[in] path Entry-point path.
  * \param[in] user_data User data pointer.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Entry-point already added.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Entry-point already added.
  * \warning It exits the application if called when no memory space is available.
  */
 SG_EXTERN int sg_entrypoints_add(struct sg_entrypoints *entrypoints, const char *path, void *user_data);
@@ -1298,9 +1298,9 @@ SG_EXTERN int sg_entrypoints_add(struct sg_entrypoints *entrypoints, const char
  * Removes an entry-point item from the entry-points \pr{entrypoints}.
  * \param[in] entrypoints Entry-points handle.
  * \param[in] path Entry-point path to be removed.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval ENOENT - Entry-point already removed.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval ENOENT Entry-point already removed.
  * \warning It exits the application if called when no memory space is available.
  */
 SG_EXTERN int sg_entrypoints_rm(struct sg_entrypoints *entrypoints, const char *path);
@@ -1310,8 +1310,8 @@ SG_EXTERN int sg_entrypoints_rm(struct sg_entrypoints *entrypoints, const char *
  * \param[in] entrypoints Entry-points handle.
  * \param[in] cb Callback to iterate the entry-point items.
  * \param[in,out] cls User-specified value.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  * \return Callback result when it is different from `0`.
  */
 SG_EXTERN int sg_entrypoints_iter(struct sg_entrypoints *entrypoints, sg_entrypoints_iter_cb cb, void *cls);
@@ -1319,8 +1319,8 @@ SG_EXTERN int sg_entrypoints_iter(struct sg_entrypoints *entrypoints, sg_entrypo
 /**
  * Cleans all existing entry-point items in the entry-points \pr{entrypoints}.
  * \param[in] entrypoints Entry-points handle.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_entrypoints_clear(struct sg_entrypoints *entrypoints);
 
@@ -1329,9 +1329,9 @@ SG_EXTERN int sg_entrypoints_clear(struct sg_entrypoints *entrypoints);
  * \param[in] entrypoints Entry-points handle.
  * \param[in,out] entrypoint Pointer of the variable to store the found entry-point.
  * \param[in] path Entry-point path to be found.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval ENOENT - Pair not found.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval ENOENT Pair not found.
  * \warning It exits the application if called when no memory space is available.
  */
 SG_EXTERN int sg_entrypoints_find(struct sg_entrypoints *entrypoints, struct sg_entrypoint **entrypoint,
@@ -1349,8 +1349,8 @@ struct sg_route;
  * \param[out] cls User-defined closure.
  * \param[out] index Current iterated item index.
  * \param[out] segment Current iterated segment.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to stop the segments iteration.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to stop the segments iteration.
  */
 typedef int (*sg_segments_iter_cb)(void *cls, unsigned int index, const char *segment);
 
@@ -1359,8 +1359,8 @@ typedef int (*sg_segments_iter_cb)(void *cls, unsigned int index, const char *se
  * \param[out] cls User-defined closure.
  * \param[out] name Current iterated variable name.
  * \param[out] val Current iterated variable value.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to stop the variables iteration.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to stop the variables iteration.
  */
 typedef int (*sg_vars_iter_cb)(void *cls, const char *name, const char *val);
 
@@ -1375,8 +1375,8 @@ typedef void (*sg_route_cb)(void *cls, struct sg_route *route);
  * Callback signature used by #sg_routes_iter() to iterate route items.
  * \param[out] cls User-defined closure.
  * \param[out] route Current iterated route.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to stop the route items iteration.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to stop the route items iteration.
  */
 typedef int (*sg_routes_iter_cb)(void *cls, struct sg_route *route);
 
@@ -1428,8 +1428,8 @@ SG_EXTERN const char *sg_route_path(struct sg_route *route);
  * \param[in] route Route handle.
  * \param[in] cb Callback to iterate the path segments.
  * \param[in,out] cls User-specified value.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  * \return Callback result when it is different from `0`.
  */
 SG_EXTERN int sg_route_segments_iter(struct sg_route *route, sg_segments_iter_cb cb, void *cls);
@@ -1439,8 +1439,8 @@ SG_EXTERN int sg_route_segments_iter(struct sg_route *route, sg_segments_iter_cb
  * \param[in] route Route handle.
  * \param[in] cb Callback to iterate the path variables.
  * \param[in,out] cls User-specified value.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  * \return Callback result when it is different from `0`.
  */
 SG_EXTERN int sg_route_vars_iter(struct sg_route *route, sg_vars_iter_cb cb, void *cls);
@@ -1462,9 +1462,9 @@ SG_EXTERN void *sg_route_user_data(struct sg_route *route);
  * \param[in] errlen Length of the error message.
  * \param[in] cb Callback to handle the path routing.
  * \param[in] cls User-defined closure.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Route already added.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Route already added.
  * \note The pattern is enclosed between `^` and `$` automatically if it does not start with `(`.
  * \note The escape sequence \\K is not supported. It causes `EINVAL` if used.
  * \note The pattern is compiled using just-in-time optimization (JIT) when it is supported.
@@ -1479,9 +1479,9 @@ SG_EXTERN int sg_routes_add2(struct sg_route **routes, struct sg_route **route,
  * \param[in] pattern Pattern as null-terminated string. It must be a valid regular expression in PCRE2 syntax.
  * \param[in] cb Callback to handle the path routing.
  * \param[in] cls User-defined closure.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval EALREADY - Route already added.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval EALREADY Route already added.
  * \note The pattern is enclosed between `^` and `$` automatically if it does not start with `(`.
  * \note The escape sequence \\K is not supported. It causes `EINVAL` if used.
  * \note The pattern is compiled using just-in-time optimization (JIT) when it is supported.
@@ -1493,9 +1493,9 @@ SG_EXTERN bool sg_routes_add(struct sg_route **routes, const char *pattern, sg_r
  * Removes a route item from the route list \pr{routes}.
  * \param[in,out] routes Route list pointer to add a new route item.
  * \param[in] pattern Pattern as null-terminated string of the route to be removed.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval ENOENT - Route already removed.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval ENOENT Route already removed.
  */
 SG_EXTERN int sg_routes_rm(struct sg_route **routes, const char *pattern);
 
@@ -1504,17 +1504,17 @@ SG_EXTERN int sg_routes_rm(struct sg_route **routes, const char *pattern);
  * \param[in] routes Route list handle.
  * \param[in] cb Callback to iterate over route items.
  * \param[in] cls User-defined closure.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval E<ERROR> - User-defined error to abort the list iteration.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval E<ERROR> User-defined error to abort the list iteration.
  */
 SG_EXTERN int sg_routes_iter(struct sg_route *routes, sg_routes_iter_cb cb, void *cls);
 
 /**
  * Returns the next route int the route list.
  * \param[in,out] route Pointer to the next route item.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
  */
 SG_EXTERN int sg_routes_next(struct sg_route **route);
 
@@ -1543,8 +1543,8 @@ struct sg_router;
  * \param[out] cls User-defined closure.
  * \param[out] path Route path as null-terminated string.
  * \param[out] route Route handle.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to stop the route dispatching loop.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to stop the route dispatching loop.
  */
 typedef int (*sg_router_dispatch_cb)(void *cls, const char *path, struct sg_route *route);
 
@@ -1552,8 +1552,8 @@ typedef int (*sg_router_dispatch_cb)(void *cls, const char *path, struct sg_rout
  * Callback signature used by #sg_router_dispatch2 when the path matches the pattern before the route dispatching.
  * \param[out] cls User-defined closure.
  * \param[out] route Route handle.
- * \retval 0 - Success.
- * \retval E<ERROR> - User-defined error to stop the route dispatching.
+ * \retval 0 Success.
+ * \retval E<ERROR> User-defined error to stop the route dispatching.
  */
 typedef int (*sg_router_match_cb)(void *cls, struct sg_route *route);
 
@@ -1580,10 +1580,10 @@ SG_EXTERN void sg_router_free(struct sg_router *router);
  * \param[in] dispatch_cb Callback triggered for each route item in the route dispatching loop.
  * \param[in] cls User-defined closure passed to the \pr{dispatch_cb} and \pr{match_cb} callbacks.
  * \param[in] match_cb Callback triggered when the path matches the route pattern.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval ENOENT - Route not found or path not matched.
- * \retval E<ERROR> - User-defined error in \pr{dispatch_cb} or \pr{match_cb}.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval ENOENT Route not found or path not matched.
+ * \retval E<ERROR> User-defined error in \pr{dispatch_cb} or \pr{match_cb}.
  * \note The route callback #sg_route_cb is triggered when the path matches the route pattern.
  * \note The match logic uses just-in-time optimization (JIT) when it is supported.
  */
@@ -1595,10 +1595,10 @@ SG_EXTERN int sg_router_dispatch2(struct sg_router *router, const char *path, vo
  * \param[in] router Router handle.
  * \param[in] path Path to dispatch a route.
  * \param[in] user_data User data pointer to be hold by the route.
- * \retval 0 - Success.
- * \retval EINVAL - Invalid argument.
- * \retval ENOENT - Route not found or path not matched.
- * \retval E<ERROR> - User-defined error in \pr{dispatch_cb} or \pr{match_cb}.
+ * \retval 0 Success.
+ * \retval EINVAL Invalid argument.
+ * \retval ENOENT Route not found or path not matched.
+ * \retval E<ERROR> User-defined error in \pr{dispatch_cb} or \pr{match_cb}.
  * \note The route callback #sg_route_cb is triggered when the path matches the route pattern.
  * \note The match logic uses just-in-time optimization (JIT) when it is supported.
  */