lib/utils: more docs

It's perhaps unfortunate that the output value of buflen had +1 change
in meaning in commit 19a3cad69, but the name clearly indicates that we
care about length of the buffer, i.e. space terminating zero *is*
counted on input, so let's be consistent and count it on output as well.

diff --git a/lib/utils.h b/lib/utils.h
index 0ec283b0c8266ae8ba2f733aca9b288eb6b2e6a2..8e4e1ad4bae36cfd1a876c6eaf6cf3c9909c9522 100644 (file)
--- a/lib/utils.h
+++ b/lib/utils.h
@@ -281,9 +281,14 @@ uint16_t kr_inaddr_port(const struct sockaddr *addr);
 /** Set port. */
 KR_EXPORT
 void kr_inaddr_set_port(struct sockaddr *addr, uint16_t port);
-/** String representation for given address as "<addr>#<port>" */
+
+/** Write string representation for given address as "<addr>#<port>".
+ * \param[in]     addr   the raw address
+ * \param[out]    buf    the buffer for output string
+ * \param[in,out] buflen the available(in) and utilized(out) length, including \0 */
 KR_EXPORT
 int kr_inaddr_str(const struct sockaddr *addr, char *buf, size_t *buflen);
+
 /** Return address type for string. */
 KR_EXPORT KR_PURE
 int kr_straddr_family(const char *addr);