Document when things were introduced

Also mention when an algorithm has been compromised

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 90 insertions, 3 deletions

diff --git a/libhashsum.h b/libhashsum.h
index 8bf38c7..5fb71cf 100644
--- a/libhashsum.h
+++ b/libhashsum.h
@@ -20,17 +20,20 @@
 
 /**
  * Hashing algorithm
+ * 
+ * @since  1.0
  */
 enum libhashsum_algorithm {
+	/* since 1.0 */
 	LIBHASHSUM_MD2,         /**< MD2 */
 	LIBHASHSUM_MD4,         /**< MD4 */
-	LIBHASHSUM_MD5,         /**< MD5 */
+	LIBHASHSUM_MD5,         /**< MD5; this algorithm has been compromised */
 	LIBHASHSUM_RIPEMD_128,  /**< RIPEMD-128 */
 	LIBHASHSUM_RIPEMD_160,  /**< RIPEMD-160 */
 	LIBHASHSUM_RIPEMD_256,  /**< RIPEMD-256 */
 	LIBHASHSUM_RIPEMD_320,  /**< RIPEMD-320 */
-	LIBHASHSUM_SHA0,        /**< SHA0 */
-	LIBHASHSUM_SHA1,        /**< SHA1 */
+	LIBHASHSUM_SHA0,        /**< SHA0; this algorithm has been compromised */
+	LIBHASHSUM_SHA1,        /**< SHA1; this algorithm has been compromised */
 	LIBHASHSUM_SHA_224,     /**< SHA-224 (SHA2) */
 	LIBHASHSUM_SHA_256,     /**< SHA-256 (SHA2) */
 	LIBHASHSUM_SHA_384,     /**< SHA-384 (SHA2) */
@@ -42,76 +45,106 @@ enum libhashsum_algorithm {
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_MD2`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_MD2_HASH_SIZE 16
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_MD4`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_MD4_HASH_SIZE 16
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_MD5`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_MD5_HASH_SIZE 16
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RIPEMD_128`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_RIPEMD_128_HASH_SIZE 16
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RIPEMD_160`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_RIPEMD_160_HASH_SIZE 20
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RIPEMD_256`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_RIPEMD_256_HASH_SIZE 32
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RIPEMD_320`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_RIPEMD_320_HASH_SIZE 40
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA0`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_SHA0_HASH_SIZE 20
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA1`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_SHA1_HASH_SIZE 20
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_224`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_SHA_224_HASH_SIZE 28
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_256`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_SHA_256_HASH_SIZE 32
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_384`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_SHA_384_HASH_SIZE 48
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_512`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_SHA_512_HASH_SIZE 64
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_512_224`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_SHA_512_224_HASH_SIZE 28
 
 /**
  * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_512_256`
+ * 
+ * @since  1.0
  */
 #define LIBHASHSUM_SHA_512_256_HASH_SIZE 32
 
@@ -218,21 +251,29 @@ union libhashsum_state {
 
 /**
  * Message hash functions and state
+ * 
+ * @since  1.0
  */
 struct libhashsum_hasher {
 	/**
 	 * The used hash algorithm
+	 * 
+	 * @since  1.0
 	 */
 	enum libhashsum_algorithm algorithm;
 
 	/**
 	 * The number of bytes required for each
 	 * call to `.process_block`
+	 * 
+	 * @since  1.0
 	 */
 	size_t input_block_size;
 
 	/**
 	 * The number of bytes in the resulting hash
+	 * 
+	 * @since  1.0
 	 */
 	size_t hash_size;
 
@@ -244,11 +285,15 @@ struct libhashsum_hasher {
 	 * to a buffer inside `.state` once `.finalise_const`
 	 * or `.finalise` has been called with successful
 	 * completion
+	 * 
+	 * @since  1.0
 	 */
 	unsigned char *hash_output;
 
 	/**
 	 * Whether the algorithm supports non-whole octet input
+	 * 
+	 * @since  1.0
 	 */
 	unsigned char supports_non_whole_bytes;
 
@@ -260,6 +305,8 @@ struct libhashsum_hasher {
 	 * @param   data   The new input data
 	 * @param   bytes  The number of bytes available in `data`
 	 * @return         The number of bytes processed from `data`
+	 * 
+	 * @since  1.0
 	 */
 	LIBHASHSUM_USERET_ LIBHASHSUM_1_NONNULL_
 	size_t (*process)(struct libhashsum_hasher *this, const void *data, size_t bytes);
@@ -276,6 +323,8 @@ struct libhashsum_hasher {
 	 * 
 	 * @throws  EINVAL  `extra_bits` is greater than 7
 	 * @throws  EINVAL  `extra_bits` is non-zero but `.supports_non_whole_bytes` is 0
+	 * 
+	 * @since  1.0
 	 */
 	LIBHASHSUM_1_NONNULL_
 	int (*finalise_const)(struct libhashsum_hasher *this, const void *data, size_t bytes, unsigned extra_bits);
@@ -294,6 +343,8 @@ struct libhashsum_hasher {
 	 * 
 	 * @throws  EINVAL  `extra_bits` is greater than 7
 	 * @throws  EINVAL  `extra_bits` is non-zero but `.supports_non_whole_bytes` is 0
+	 * 
+	 * @since  1.0
 	 */
 	LIBHASHSUM_1_NONNULL_
 	int (*finalise)(struct libhashsum_hasher *this, void *data, size_t bytes, unsigned extra_bits, size_t size);
@@ -302,6 +353,8 @@ struct libhashsum_hasher {
 	 * The hash state
 	 * 
 	 * For internal use
+	 * 
+	 * @since  1.0
 	 */
 	union libhashsum_state state;
 };
@@ -316,6 +369,8 @@ struct libhashsum_hasher {
  * @return             0 on success, -1 on failure
  * 
  * @throws  EINVAL  `algorithm` is unsupported
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_hasher(struct libhashsum_hasher *this, enum libhashsum_algorithm algorithm);
@@ -328,6 +383,8 @@ int libhashsum_init_hasher(struct libhashsum_hasher *this, enum libhashsum_algor
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_md2_hasher(struct libhashsum_hasher *this);
@@ -340,6 +397,8 @@ int libhashsum_init_md2_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_md4_hasher(struct libhashsum_hasher *this);
@@ -352,6 +411,8 @@ int libhashsum_init_md4_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_md5_hasher(struct libhashsum_hasher *this);
@@ -364,6 +425,8 @@ int libhashsum_init_md5_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_ripemd_128_hasher(struct libhashsum_hasher *this);
@@ -376,6 +439,8 @@ int libhashsum_init_ripemd_128_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_ripemd_160_hasher(struct libhashsum_hasher *this);
@@ -388,6 +453,8 @@ int libhashsum_init_ripemd_160_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_ripemd_256_hasher(struct libhashsum_hasher *this);
@@ -400,6 +467,8 @@ int libhashsum_init_ripemd_256_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_ripemd_320_hasher(struct libhashsum_hasher *this);
@@ -412,6 +481,8 @@ int libhashsum_init_ripemd_320_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_sha0_hasher(struct libhashsum_hasher *this);
@@ -424,6 +495,8 @@ int libhashsum_init_sha0_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_sha1_hasher(struct libhashsum_hasher *this);
@@ -436,6 +509,8 @@ int libhashsum_init_sha1_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_sha_224_hasher(struct libhashsum_hasher *this);
@@ -448,6 +523,8 @@ int libhashsum_init_sha_224_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_sha_256_hasher(struct libhashsum_hasher *this);
@@ -460,6 +537,8 @@ int libhashsum_init_sha_256_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_sha_384_hasher(struct libhashsum_hasher *this);
@@ -472,6 +551,8 @@ int libhashsum_init_sha_384_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_sha_512_hasher(struct libhashsum_hasher *this);
@@ -484,6 +565,8 @@ int libhashsum_init_sha_512_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_sha_512_224_hasher(struct libhashsum_hasher *this);
@@ -496,6 +579,8 @@ int libhashsum_init_sha_512_224_hasher(struct libhashsum_hasher *this);
  * @return        0 on success, -1 on failure
  * 
  * Failure isn't actually possible, so this function always return 0
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_sha_512_256_hasher(struct libhashsum_hasher *this);
@@ -513,6 +598,8 @@ int libhashsum_init_sha_512_256_hasher(struct libhashsum_hasher *this);
  * @throws  EINVAL  `hashbits` is invalid (neither 224, 256, 384, nor 512)
  * @throws  EINVAL  The combination of `algobits` and `hashbits` is invalid
  *                  (`hashbits` is 384 or 512 but `algobits` is 32)
+ * 
+ * @since  1.0
  */
 LIBHASHSUM_1_NONNULL_
 int libhashsum_init_sha2_hasher(struct libhashsum_hasher *this, unsigned algobits, size_t hashbits);