nats: FIX: homogenize return codes and update API documentation

This patch standardizes the return codes:
- 0 on success
- -EIO on network error
- -EINVAL if an invalid parameter was passed as argument or
   received from the server

API documentation is also updated to reflect those changes.

Change-Id: I076d195fde7c6b32b4a52454f312fb8cd8ce2332
Signed-off-by: Flavio Santes <flavio.santes@intel.com>

samples/net/nats_clients/publisher/src/nats_client.c

@@ -84,7 +84,7 @@ int nats_sub(struct nats_clapp_ctx_t *ctx, char *subject, char *queue_grp,
 
 	rc = netz_tx(ctx->netz_ctx, ctx->tx_buf);
 	if (rc != 0) {
-		return rc;
+		return -EIO;
 	}
 
 	return nats_read_ok(ctx);
@@ -95,10 +95,13 @@ int nats_unsub(struct nats_clapp_ctx_t *ctx, char *sid, int max_msgs)
 	int rc;
 
 	rc = nats_pack_unsub(ctx->tx_buf, sid, max_msgs);
+	if (rc != 0) {
+		return -EINVAL;
+	}
 
 	rc = netz_tx(ctx->netz_ctx, ctx->tx_buf);
 	if (rc != 0) {
-		return rc;
+		return -EIO;
 	}
 
 	return nats_read_ok(ctx);

samples/net/nats_clients/publisher/src/nats_client.h

@@ -45,7 +45,9 @@ struct nats_clapp_ctx_t {
  * @param [in] verbose		Verbose mode
  * @return			0 on success
  * @return			-EIO on network error
- * @return			-EINVAL
+ * @return			-EINVAL if an invalid parameter was
+ *				passed as argument or received from the
+ *				server.
  */
 int nats_connect(struct nats_clapp_ctx_t *ctx, char *client_name, int verbose);
 
@@ -57,7 +59,9 @@ int nats_connect(struct nats_clapp_ctx_t *ctx, char *client_name, int verbose);
  * @param [in] payload		Message payload
  * @return			0 on success
  * @return			-EIO on network error
- * @return			-EINVAL
+ * @return			-EINVAL if an invalid parameter was
+ *				passed as argument or received from the
+ *				server.
  */
 int nats_pub(struct nats_clapp_ctx_t *ctx, char *subject, char *reply_to,
 	     char *payload);
@@ -70,7 +74,9 @@ int nats_pub(struct nats_clapp_ctx_t *ctx, char *subject, char *reply_to,
  * @param [in] sid		Subscription Identifier
  * @return			0 on success
  * @return			-EIO on network error
- * @return			-EINVAL
+ * @return			-EINVAL if an invalid parameter was
+ *				passed as argument or received from the
+ *				server.
  */
 int nats_sub(struct nats_clapp_ctx_t *ctx, char *subject, char *queue_grp,
 	     char *sid);
@@ -80,7 +86,11 @@ int nats_sub(struct nats_clapp_ctx_t *ctx, char *subject, char *queue_grp,
  * @param [in] ctx		NATS Client Application Context structure
  * @param [in] sid		Subscription Identifier
  * @param [in] max_msgs		Max messages field
- * @return
+ * @return			0 on success
+ * @return			-EIO on network error
+ * @return			-EINVAL if an invalid parameter was
+ *				passed as argument or received from the
+ *				server.
  */
 int nats_unsub(struct nats_clapp_ctx_t *ctx, char *sid, int max_msgs);
 
@@ -88,8 +98,10 @@ int nats_unsub(struct nats_clapp_ctx_t *ctx, char *sid, int max_msgs);
  * @brief nats_read_ok		Reads the +OK message
  * @param [in] ctx		NATS Client Application Context structure
  * @return			0 on success
- * @return			-EIO on error
- * @return			-EINVAL
+ * @return			-EIO on network error
+ * @return			-EINVAL if an invalid parameter was
+ *				passed as argument or received from the
+ *				server.
  */
 int nats_read_ok(struct nats_clapp_ctx_t *ctx);
 
@@ -99,7 +111,9 @@ int nats_read_ok(struct nats_clapp_ctx_t *ctx);
  * @param [in] ctx		NATS Client Application Context structure
  * @return			0 on success
  * @return			-EIO on network error
- * @return			-EINVAL
+ * @return			-EINVAL if an invalid parameter was
+ *				passed as argument or received from the
+ *				server.
  */
 int nats_ping_pong(struct nats_clapp_ctx_t *ctx);
 

samples/net/nats_clients/publisher/src/nats_pack.c

@@ -22,8 +22,9 @@
 #include <ctype.h>
 #include <errno.h>
 
-/* NATS require to send the language and version.
- * So we send the GCC version. It could be any string.
+/* NATS requires that the app's language and version
+ * are included in the CONNECT message.
+ * So, here we send the GCC version. It could be anything.
  */
 #ifdef __GNUC__
 #define CLANG		"GCC"