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>