Fix documentation

Author: Warchant

include/ed25519/ed25519.h

@@ -21,7 +21,7 @@ typedef struct { unsigned char data[ed25519_privkey_SIZE]; } private_key_t;
  * @brief Generates a keypair. Depends on randombytes.h random generator.
  * @param[out] sk allocated buffer of ed25519_privkey_SIZE
  * @param[out] pk allocated buffer of ed25519_pubkey_SIZE
- * @return 0 if success, non-0 otherwise
+ * @return 1 if success, non-0 otherwise
  */
 int ed25519_create_keypair(private_key_t* sk, public_key_t* pk);
 

include/ed25519/randombytes.h

@@ -7,9 +7,9 @@ extern "C" {
 
 /**
  * Fills preallocated buffer p of length len with random data.
- * @param p buffer of length len
- * @param len length
- * @return 0 if success, non-0 otherwise
+ * @param[out] p buffer of length len
+ * @param[in] len length
+ * @return 1 if success, non-0 otherwise
  * @note You should always check return code of randombytes
  */
 extern int randombytes(unsigned char *p, int len);

include/ed25519/sha512.h

@@ -15,35 +15,39 @@ extern const unsigned int SHA_CONTEXT_SIZE;
 
 /**
  * Initializes context with specific for implementation size.
- * @param context always pass preallocated buffer of SHA_CONTEXT_SIZE;
- * @return 0 if success, non-0 otherwise.
+ * @param[in] context always pass preallocated buffer of SHA_CONTEXT_SIZE;
+ * @return 0 if error, non-0 otherwise.
+ * @note some implementations may return bad code sometimes, some may not
  */
 extern int sha512_init(void *context);
 
 /**
  * Updates hash state with given buffer
- * @param context always pass preallocated buffer of SHA_CONTEXT_SIZE;
- * @param in input buffer with info to be hashed
- * @param inlen buffer size
- * @return 0 if success, non-0 otherwise
+ * @param[in] context always pass preallocated buffer of SHA_CONTEXT_SIZE;
+ * @param[in] in input buffer with info to be hashed
+ * @param[in] inlen buffer size
+ * @return 0 if error, non-0 otherwise
+ * @note some implementations may return bad code sometimes, some may not
  */
 extern int sha512_update(void *context, const unsigned char *in,
                          unsigned long long inlen);
 
 /**
  * Finish hash calculation. Use this to store hash in output buffer (out).
- * @param context always pass preallocated buffer of SHA_CONTEXT_SIZE;
- * @param out output buffer of exactly SHA_512_SIZE bytes
- * @return 0 if success, non-0 otherwise
+ * @param[in] context always pass preallocated buffer of SHA_CONTEXT_SIZE;
+ * @param[in] out output buffer of exactly SHA_512_SIZE bytes
+ * @return 0 if error, non-0 otherwise
+ * @note some implementations may return bad code sometimes, some may not
  */
 extern int sha512_final(void *context, unsigned char *out);
 
 /**
  * Inline hash calculation of sha512.
- * @param out output buffer of exactly SHA_512_SIZE bytes
- * @param message message buffer to be hashed
- * @param message_len size of the message buffer
- * @return 0 if success, non-0 otherwise
+ * @param[out] out output buffer of exactly SHA_512_SIZE bytes
+ * @param[in] message message buffer to be hashed
+ * @param[in] message_len size of the message buffer
+ * @return 0 if error, non-0 otherwise
+ * @note some implementations may return bad code sometimes, some may not
  */
 extern int sha512(unsigned char *out, const unsigned char *message,
                   unsigned long long message_len);