From a8c00f2af9c6c3462e547a30eb11297a3bbfc35c Mon Sep 17 00:00:00 2001 From: Jon Shallow Date: Wed, 2 Feb 2022 17:03:04 +0000 Subject: [PATCH] coap_pdu_setup.txt.in: Better document coap_encode_var_safe8() Document return value can be 0 for both being valid and returning on error. Same is true for coap_encode_var_safe(). [Error should assert() by default] --- include/coap3/encode.h | 6 ++++-- man/coap_pdu_setup.txt.in | 8 ++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/include/coap3/encode.h b/include/coap3/encode.h index b33840f0..cc1623d2 100644 --- a/include/coap3/encode.h +++ b/include/coap3/encode.h @@ -78,7 +78,8 @@ uint64_t coap_decode_var_bytes8(const uint8_t *buf, size_t length); * @param length The output buffer size to encode into (must be sufficient) * @param value The value to encode into the buffer * - * @return The number of bytes used to encode @p value or @c 0 on error. + * @return The number of bytes used to encode @p value (which can be 0 + * when encoding value of 0) or @c 0 on error. */ unsigned int coap_encode_var_safe(uint8_t *buf, size_t length, @@ -94,7 +95,8 @@ unsigned int coap_encode_var_safe(uint8_t *buf, * @param length The output buffer size to encode into (must be sufficient) * @param value The value to encode into the buffer * - * @return The number of bytes used to encode @p value or @c 0 on error. + * @return The number of bytes used to encode @p value (which can be 0 + * when encoding value of 0) or @c 0 on error. */ unsigned int coap_encode_var_safe8(uint8_t *buf, size_t length, diff --git a/man/coap_pdu_setup.txt.in b/man/coap_pdu_setup.txt.in index 308ad128..c54f39d8 100644 --- a/man/coap_pdu_setup.txt.in +++ b/man/coap_pdu_setup.txt.in @@ -248,7 +248,7 @@ of the data of the option, and _data_ points to the content of the option. *NOTE:* Where possible, the option data needs to be stripped of leading zeros (big endian) to reduce the amount of data needed in the PDU, as well as in -some cases the maximum data size of an opton can be exceeded if not stripped +some cases the maximum data size of an option can be exceeded if not stripped and hence be illegal. This is done by using coap_encode_var_safe() or coap_encode_var_safe8(). @@ -327,7 +327,7 @@ being the same or greater than the previous option _number_ that was added. *NOTE:* Where possible, the option data needs to be stripped of leading zeros (big endian) to reduce the amount of data needed in the PDU, as well as in -some cases the maximum data size of an opton can be exceeded if not stripped +some cases the maximum data size of an option can be exceeded if not stripped and hence be illegal. This is done by using coap_encode_var_safe() or coap_encode_var_safe8(). @@ -394,10 +394,10 @@ The *coap_add_optlist*() function returns either the length of the option or 0 on failure. The *coap_encode_var_safe*() function returns either the length of bytes -encoded or 0 on failure. +encoded (which can be 0 when encoding 0) or 0 on failure. The *coap_encode_var_safe8*() function returns either the length of bytes -encoded or 0 on failure. +encoded (which can be 0 when encoding 0) or 0 on failure. The *coap_send*() function returns the CoAP message ID on success or COAP_INVALID_MID on failure.