sys/include/net: better documentation of nanocoap_sock_request_cb

fabian18 · fabian18 · commit 02e513e04bee · 2024-09-10T16:44:19.000+02:00
diff --git a/sys/include/net/nanocoap_sock.h b/sys/include/net/nanocoap_sock.h
@@ -384,7 +384,7 @@ static inline void nanocoap_sock_close(nanocoap_sock_t *sock)
  * @param[in]   len     length of @p buffer
  *
  * @returns     length of response payload on success
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_sock_get(nanocoap_sock_t *sock, const char *path, void *buf,
                           size_t len);
@@ -398,7 +398,7 @@ ssize_t nanocoap_sock_get(nanocoap_sock_t *sock, const char *path, void *buf,
  * @param[in]   len_max length of @p response
  *
  * @returns     length of response payload on success
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_sock_get_non(nanocoap_sock_t *sock, const char *path,
                               void *response, size_t len_max);
@@ -414,7 +414,7 @@ ssize_t nanocoap_sock_get_non(nanocoap_sock_t *sock, const char *path,
  * @param[in]   len_max length of @p response
  *
  * @returns     length of response payload on success
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_sock_put(nanocoap_sock_t *sock, const char *path,
                           const void *request, size_t len,
@@ -433,7 +433,7 @@ ssize_t nanocoap_sock_put(nanocoap_sock_t *sock, const char *path,
  * @returns     length of response payload on success
  * @returns     0 if the request was sent and no response buffer was provided,
  *              independently of success (because no response is requested in that case)
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_sock_put_non(nanocoap_sock_t *sock, const char *path,
                               const void *request, size_t len,
@@ -466,7 +466,7 @@ ssize_t nanocoap_sock_put_url(const char *url,
  * @param[in]   len_max length of @p response
  *
  * @returns     length of response payload on success
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_sock_post(nanocoap_sock_t *sock, const char *path,
                            const void *request, size_t len,
@@ -485,7 +485,7 @@ ssize_t nanocoap_sock_post(nanocoap_sock_t *sock, const char *path,
  * @returns     length of response payload on success
  * @returns     0 if the request was sent and no response buffer was provided,
  *              independently of success (because no response is requested in that case)
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_sock_post_non(nanocoap_sock_t *sock, const char *path,
                                const void *request, size_t len,
@@ -519,7 +519,7 @@ ssize_t nanocoap_sock_post_url(const char *url,
  * @param[in]   len_max length of @p response
  *
  * @returns     length of response payload on success
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_sock_fetch(nanocoap_sock_t *sock, const char *path,
                             const void *request, size_t len,
@@ -539,7 +539,7 @@ ssize_t nanocoap_sock_fetch(nanocoap_sock_t *sock, const char *path,
  * @returns     length of response payload on success
  * @returns     0 if the request was sent and no response buffer was provided,
  *              independently of success (because no response is requested in that case)
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_sock_fetch_non(nanocoap_sock_t *sock, const char *path,
                                 const void *request, size_t len,
@@ -569,7 +569,7 @@ ssize_t nanocoap_sock_fetch_url(const char *url,
  * @param[in]   path    remote path (with query) to delete
  *
  * @returns     0 on success
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_sock_delete(nanocoap_sock_t *sock, const char *path);
 
@@ -716,7 +716,15 @@ ssize_t nanocoap_sock_request(nanocoap_sock_t *sock, coap_pkt_t *pkt, size_t len
  * @param[in]       arg     Optional callback argumnent
  *
  * @returns     length of response on success
- * @returns     <0 on error
+ * @returns     0 for a request for which no response is expected, indicated by @p cb == NULL,
+ *              or for a 2.xx response
+ * @returns     -ETIMEDOUT, if no matching ACK or no response was received
+ * @returns     -EBADMSG, if a matching RST was received
+ * @returns     -ENXIO, if @p cb == NULL and the response indicates a 4.xx client error
+ * @returns     -ENETRESET, if @p cb == NULL and the response indicates a 5.xx server error
+ * @returns     any error on @see sock_udp_sendv or @see sock_dtls_sendv
+ * @returns     any error on @see sock_udp_recv_buf or @see sock_dtls_recv_buf
+ * @returns     any return value of @p cb for a matching response
  */
 ssize_t nanocoap_sock_request_cb(nanocoap_sock_t *sock, coap_pkt_t *pkt,
                                  coap_request_cb_t cb, void *arg);
@@ -732,7 +740,7 @@ ssize_t nanocoap_sock_request_cb(nanocoap_sock_t *sock, coap_pkt_t *pkt,
  *                          request
  *
  * @returns     length of response on success
- * @returns     <0 on error
+ * @returns     @see nanocoap_sock_request_cb on error
  */
 ssize_t nanocoap_request(coap_pkt_t *pkt, const sock_udp_ep_t *local,
                          const sock_udp_ep_t *remote, size_t len);
