docs: audit api return information

https://github.com/warmcat/libwebsockets/issues/2481

11 files changed, 36 insertions, 28 deletions

diff --git a/include/libwebsockets/lws-client.h b/include/libwebsockets/lws-client.h
index 4b7fa8cd..bb5f2d03 100644
--- a/include/libwebsockets/lws-client.h
+++ b/include/libwebsockets/lws-client.h
@@ -313,6 +313,7 @@ lws_http_client_read(struct lws *wsi, char **buf, int *len);
  * \param wsi: client connection
  *
  * Returns the last server response code, eg, 200 for client http connections.
+ * If there is no valid response, it will return 0.
  *
  * You should capture this during the LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP
  * callback, because after that the memory reserved for storing the related
diff --git a/include/libwebsockets/lws-genec.h b/include/libwebsockets/lws-genec.h
index c18cc1e1..5ae1d2f7 100644
--- a/include/libwebsockets/lws-genec.h
+++ b/include/libwebsockets/lws-genec.h
@@ -184,7 +184,7 @@ lws_genecdsa_hash_sig_verify_jws(struct lws_genec_ctx *ctx, const uint8_t *in,
  * \param sig: pointer to buffer to take signature
  * \param sig_len: length of the buffer (must be >= length of key N)
  *
- * Returns <0 for error, or 0 for success.
+ * Returns <0 for error, or >=0 for success.
  *
  * This creates a JWS ECDSA signature for a hash you already computed and provide.
  *
diff --git a/include/libwebsockets/lws-genhash.h b/include/libwebsockets/lws-genhash.h
index 8407d2f0..f27c3b91 100644
--- a/include/libwebsockets/lws-genhash.h
+++ b/include/libwebsockets/lws-genhash.h
@@ -93,7 +93,8 @@ struct lws_genhmac_ctx {
  *
  * \param type:	one of LWS_GENHASH_TYPE_...
  *
- * Returns number of bytes in this type of hash
+ * Returns number of bytes in this type of hash, if the hash type is unknown, it
+ * will return 0.
  */
 LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT
 lws_genhash_size(enum lws_genhash_types type);
@@ -102,7 +103,8 @@ lws_genhash_size(enum lws_genhash_types type);
  *
  * \param type:	one of LWS_GENHASH_TYPE_...
  *
- * Returns number of bytes in this type of hmac
+ * Returns number of bytes in this type of hmac, if the hmac type is unknown, it
+ * will return 0.
  */
 LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT
 lws_genhmac_size(enum lws_genhmac_types type);
diff --git a/include/libwebsockets/lws-genrsa.h b/include/libwebsockets/lws-genrsa.h
index c9409463..3f230312 100644
--- a/include/libwebsockets/lws-genrsa.h
+++ b/include/libwebsockets/lws-genrsa.h
@@ -216,7 +216,7 @@ lws_genrsa_hash_sig_verify(struct lws_genrsa_ctx *ctx, const uint8_t *in,
  * \param sig: pointer to buffer to take signature
  * \param sig_len: length of the buffer (must be >= length of key N)
  *
- * Returns <0 for error, or 0 for success.
+ * Returns <0 for error, or \p sig_len for success.
  *
  * This creates an RSA signature for a hash you already computed and provide.
  * You should have created the hash before calling this by iterating over the
diff --git a/include/libwebsockets/lws-http.h b/include/libwebsockets/lws-http.h
index 9d609032..2c5bd64d 100644
--- a/include/libwebsockets/lws-http.h
+++ b/include/libwebsockets/lws-http.h
@@ -866,7 +866,7 @@ lws_http_redirect(struct lws *wsi, int code, const unsigned char *loc, int len,
  * lws_http_transaction_completed() - wait for new http transaction or close
  * \param wsi:	websocket connection
  *
- *	Returns 1 if the HTTP connection must close now
+ *	Returns nonzero if the HTTP connection must close now
  *	Returns 0 and resets connection to wait for new HTTP header /
  *	  transaction if possible
  */
diff --git a/include/libwebsockets/lws-jose.h b/include/libwebsockets/lws-jose.h
index 247d02c6..c780c0e2 100644
--- a/include/libwebsockets/lws-jose.h
+++ b/include/libwebsockets/lws-jose.h
@@ -189,7 +189,8 @@ lws_gencrypto_jwe_enc_to_definition(const char *enc,
  * \param temp: parent-owned buffer to "allocate" elements into
  * \param temp_len: amount of space available in temp
  *
- * returns the amount of temp used, or -1 for error
+ * returns 0 for success, or -1 for error
+ * *\p temp_len is updated to reflect the amount of \p temp used if successful.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_jws_parse_jose(struct lws_jose *jose,
@@ -204,7 +205,8 @@ lws_jws_parse_jose(struct lws_jose *jose,
  * \param temp: parent-owned buffer to "allocate" elements into
  * \param temp_len: amount of space available in temp
  *
- * returns the amount of temp used, or -1 for error
+ * returns 0 for success, or -1 for error
+ * *\p temp_len is updated to reflect the amount of \p temp used if successful.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_jwe_parse_jose(struct lws_jose *jose,
diff --git a/include/libwebsockets/lws-jwk.h b/include/libwebsockets/lws-jwk.h
index bf33b804..a2205d2e 100644
--- a/include/libwebsockets/lws-jwk.h
+++ b/include/libwebsockets/lws-jwk.h
@@ -193,7 +193,7 @@ lws_jwk_rfc7638_fingerprint(struct lws_jwk *jwk, char *digest32);
  * \param in: string to copy
  * \param len: length of string to copy
  *
- * Returns 0 for OK or -1 for failure
+ * Returns 0 for OK or nonzero for failure
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_jwk_strdup_meta(struct lws_jwk *jwk, enum enum_jwk_meta_tok idx,
@@ -211,7 +211,7 @@ lws_jwk_dump(struct lws_jwk *jwk);
  * \param bits: for OCT and RSA keys, the number of bits
  * \param curve: for EC keys, the name of the curve
  *
- * Returns 0 for OK or -1 for failure
+ * Returns 0 for OK or nonzero for failure
  */
 LWS_VISIBLE int
 lws_jwk_generate(struct lws_context *context, struct lws_jwk *jwk,
diff --git a/include/libwebsockets/lws-jws.h b/include/libwebsockets/lws-jws.h
index 0ad4714b..f15d503c 100644
--- a/include/libwebsockets/lws-jws.h
+++ b/include/libwebsockets/lws-jws.h
@@ -111,7 +111,7 @@ lws_jws_destroy(struct lws_jws *jws);
  * in a map... it'll make a temp b64 version needed for comparison.  See below
  * for other variants.
  *
- * Returns 0 on match.
+ * Returns 0 on match, else nonzero.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_jws_sig_confirm_compact(struct lws_jws_map *map, struct lws_jwk *jwk,
@@ -139,7 +139,7 @@ lws_jws_sig_confirm_compact_b64_map(struct lws_jws_map *map_b64,
  * (jose.payload.hdr.sig) as an aggregated string... it'll make a temp plain
  * version needed for comparison.
  *
- * Returns 0 on match.
+ * Returns 0 on match, else nonzero.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_jws_sig_confirm_compact_b64(const char *in, size_t len,
@@ -163,7 +163,7 @@ lws_jws_sig_confirm_compact_b64(const char *in, size_t len,
  * will end up with both maps, and can use this api version, saving needlessly
  * regenerating any temp map.
  *
- * Returns 0 on match.
+ * Returns 0 on match, else nonzero.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_jws_sig_confirm(struct lws_jws_map *map_b64, /* b64-encoded */
@@ -187,7 +187,9 @@ lws_jws_sig_confirm(struct lws_jws_map *map_b64, /* b64-encoded */
  * case \p b64_hdr may be NULL, and only the payload will be hashed before
  * signing.
  *
- * Returns the length of the encoded signature written to \p b64_sig, or -1.
+ * If successful, returns the length of the encoded signature written to
+ * \p b64_sig.  If the jose signing type is unknown, 0 is returned.  Otherwise
+ * -1 indicates failure.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_jws_sign_from_b64(struct lws_jose *jose, struct lws_jws *jws, char *b64_sig,
@@ -556,7 +558,7 @@ struct lws_jwt_sign_set_cookie {
 };
 
 /**
- * lws_jwt_sign_token_set_cookie() - creates sets a JWT in a wsi cookie
+ * lws_jwt_sign_token_set_http_cookie() - creates sets a JWT in a wsi cookie
  *
  * \param wsi: the wsi to create the cookie header on
  * \param i: structure describing what should be in the JWT
diff --git a/include/libwebsockets/lws-network-helper.h b/include/libwebsockets/lws-network-helper.h
index 4ad16bef..20a32253 100644
--- a/include/libwebsockets/lws-network-helper.h
+++ b/include/libwebsockets/lws-network-helper.h
@@ -223,8 +223,9 @@ lws_sa46_parse_numeric_address(const char *ads, lws_sockaddr46 *sa46);
  * \param len: max size of text buffer
  *
  * Converts an array of network-ordered byte address elements to a textual
- * representation of the numeric address, like "1.2.3.4" or "::1".  Return 0
- * if OK else < 0.  ipv6 only supported with LWS_IPV6=1 at cmake.
+ * representation of the numeric address, like "1.2.3.4" or "::1".  Returns the
+ * number of chars written into buf, else < 0.  ipv6 only supported with
+ * LWS_IPV6=1 at cmake.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_write_numeric_address(const uint8_t *ads, int size, char *buf, size_t len);
@@ -237,8 +238,9 @@ lws_write_numeric_address(const uint8_t *ads, int size, char *buf, size_t len);
  * \param len: max size of text buffer
  *
  * Converts the ipv4 or ipv6 address in an lws_sockaddr46 to a textual
- * representation of the numeric address, like "1.2.3.4" or "::1".  Return 0
- * if OK else < 0.  ipv6 only supported with LWS_IPV6=1 at cmake.
+ * representation of the numeric address, like "1.2.3.4" or "::1".  Returns the
+ * number of chars written into buf, else < 0.  ipv6 only supported with
+ * LWS_IPV6=1 at cmake.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_sa46_write_numeric_address(lws_sockaddr46 *sa46, char *buf, size_t len);
diff --git a/include/libwebsockets/lws-secure-streams-client.h b/include/libwebsockets/lws-secure-streams-client.h
index adca1db1..4d24cbae 100644
--- a/include/libwebsockets/lws-secure-streams-client.h
+++ b/include/libwebsockets/lws-secure-streams-client.h
@@ -223,8 +223,7 @@ lws_sspc_request_tx_len(struct lws_sspc_handle *h, unsigned long len);
  *
  * \param h: secure streams handle
  *
- * Starts the connection process for the secure stream.  Returns 0 if OK or
- * nonzero if we have already failed.
+ * Starts the connection process for the secure stream.  Returns 0.
  */
 LWS_VISIBLE LWS_EXTERN lws_ss_state_return_t
 lws_sspc_client_connect(struct lws_sspc_handle *h);
@@ -292,7 +291,7 @@ lws_sspc_rideshare(struct lws_sspc_handle *h);
  * when the policy is using h1 is interpreted to add h1 headers of the given
  * name with the value of the metadata on the left.
  *
- * Return 0 if OK.
+ * Return 0 if OK, or nonzero if failed.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_sspc_set_metadata(struct lws_sspc_handle *h, const char *name,
diff --git a/include/libwebsockets/lws-x509.h b/include/libwebsockets/lws-x509.h
index 17a834c1..e60d6d16 100644
--- a/include/libwebsockets/lws-x509.h
+++ b/include/libwebsockets/lws-x509.h
@@ -106,7 +106,7 @@ lws_x509_create(struct lws_x509_cert **x509);
  * IMPORTANT for compatibility with mbedtls, the last used byte of \p pem
  * must be '\0' and the \p len must include it.
  *
- * Returns 0 if all went OK.
+ * Returns 0 if all went OK, or nonzero for failure.
  */
 LWS_VISIBLE LWS_EXTERN int
 lws_x509_parse_from_pem(struct lws_x509_cert *x509, const void *pem, size_t len);
@@ -192,8 +192,8 @@ lws_x509_info(struct lws_x509_cert *x509, enum lws_tls_cert_info type,
  * lws_tls_peer_cert_info() lets you get hold of information from the peer
  * certificate.
  *
- * Return 0 if there is a result in \p buf, or -1 indicating there was no cert
- * or another problem.
+ * Return 0 if there is a result in \p buf, or nonzero indicating there was no
+ * cert, or another problem.
  *
  * This function works the same no matter if the TLS backend is OpenSSL or
  * mbedTLS.
@@ -213,8 +213,8 @@ lws_tls_peer_cert_info(struct lws *wsi, enum lws_tls_cert_info type,
  * lws_tls_vhost_cert_info() lets you get hold of information from the vhost
  * certificate.
  *
- * Return 0 if there is a result in \p buf, or -1 indicating there was no cert
- * or another problem.
+ * Return 0 if there is a result in \p buf, or nonzero indicating there was no
+ * cert, or another problem.
  *
  * This function works the same no matter if the TLS backend is OpenSSL or
  * mbedTLS.
@@ -232,8 +232,8 @@ lws_tls_vhost_cert_info(struct lws_vhost *vhost, enum lws_tls_cert_info type,
  * \param san_b: second SAN written into the certificate
  *
  *
- * Returns 0 if created and attached to the vhost.  Returns -1 if problems and
- * frees all allocations before returning.
+ * Returns 0 if created and attached to the vhost.  Returns nonzero if problems,
+ * and frees all allocations before returning.
  *
  * On success, any allocations are destroyed at vhost destruction automatically.
  */