From e1bebed512298922a3cf591e1db927718d4acde0 Mon Sep 17 00:00:00 2001
From: Ken Bannister <kb2ma@runbox.com>
Date: Wed, 23 Jan 2019 13:12:37 -0500
Subject: [PATCH] net/nanocoap: make reply doc more specific
---
sys/include/net/nanocoap.h | 11 ++++++++---
1 file changed, 8 insertions(+), 3 deletions(-)
diff --git a/sys/include/net/nanocoap.h b/sys/include/net/nanocoap.h
index 2e2043fb34..00e716f50c 100644
--- a/sys/include/net/nanocoap.h
+++ b/sys/include/net/nanocoap.h
@@ -322,8 +322,11 @@ int coap_parse(coap_pkt_t *pkt, uint8_t *buf, size_t len);
*
* This function can be used to create a reply to any CoAP request packet. It
* will create the reply packet header based on parameters from the request
- * (e.g., id, token). Passing a non-zero @p payload_len will ensure the payload
- * fits into the buffer along with the header.
+ * (e.g., id, token).
+ *
+ * Passing a non-zero @p payload_len will ensure the payload fits into the
+ * buffer along with the header. For this validation, payload_len must include
+ * any options, the payload marker, as well as the payload proper.
*
* @param[in] pkt packet to reply to
* @param[in] code reply code (e.g., COAP_CODE_204)
@@ -333,6 +336,7 @@ int coap_parse(coap_pkt_t *pkt, uint8_t *buf, size_t len);
*
* @returns size of reply packet on success
* @returns <0 on error
+ * @returns -ENOSPC if @p rbuf too small
*/
ssize_t coap_build_reply(coap_pkt_t *pkt, unsigned code,
uint8_t *rbuf, unsigned rlen, unsigned payload_len);
@@ -343,7 +347,7 @@ ssize_t coap_build_reply(coap_pkt_t *pkt, unsigned code,
* This is a simple wrapper that allows for building CoAP replies for simple
* use-cases.
*
- * The reply will be written to @p buf. Is @p payload and @p payload_len
+ * The reply will be written to @p buf. If @p payload and @p payload_len are
* non-zero, the payload will be copied into the resulting reply packet.
*
* @param[in] pkt packet to reply to
@@ -356,6 +360,7 @@ ssize_t coap_build_reply(coap_pkt_t *pkt, unsigned code,
*
* @returns size of reply packet on success
* @returns <0 on error
+ * @returns -ENOSPC if @p buf too small
*/
ssize_t coap_reply_simple(coap_pkt_t *pkt,
unsigned code,
--
GitLab