Merge pull request #9858 from jia200x/pr/doc_hashes

doc: refactor `hashes` group

sys/checksum/doc.txt

@@ -9,7 +9,7 @@
 
 /**
  * @defgroup    sys_checksum Checksum
- * @ingroup     sys
+ * @ingroup     sys_hashes
  * @brief       Checksum function libraries
  *
  * This module provides a number of checksum functions. Most notably is the

sys/hashes/doc.txt

@@ -10,29 +10,25 @@
  * @defgroup    sys_hashes Hashes
  * @ingroup     sys
  *
- * @brief       A collection of hash algorithms.
+ * @brief       A collection of hash algorithms. RIOT supports some checksum
- *
+ *              hash algorithms, keyed and unkeyed cryptographic hash algorithms
- * RIOT supports the following hash functions:
+ *              and non cryptographic hash algorithms.
- *
+ */
- * @section Checksums
+
- *
+/**
- * * Fletcher-16
+ * @defgroup    sys_hashes_non_crypto Non-cryptographic hash functions
- * * Fletcher-32
+ * @ingroup     sys_hashes
- *
+ * @brief       A collection of non-cryptographic hash algorithms.
- * @section Non-cryptographic hash functions
+ */
- *
+
- * * Bernstein hash djb2i (http://www.cse.yorku.ca/~oz/hash.html)
+/**
- * * sdbm (http://www.cse.yorku.ca/~oz/hash.html)
+ * @defgroup    sys_hashes_unkeyed Unkeyed cryptographic hash functions
- * * Kernighan and Ritchie
+ * @ingroup     sys_hashes
- * * Shift, And, Xor
+ * @brief       A collection of unkeyed cryptographic hash algorithms.
- * * Donald E. Knuth
+ */
- * * Fowler-Noll-Vo hash function
+
- * * Rotating Hash
+/**
- * * One at a time Hash
+ * @defgroup    sys_hashes_keyed Keyed cryptographic hash functions
- *
+ * @ingroup     sys_hashes
- * @section Unkeyed cryptographic hash functions
+ * @brief       A collection of keyed cryptographic hash algorithms.
- *
- * * MD5
- * * SHA-256
- *
  */

sys/include/hashes.h

@@ -7,7 +7,7 @@
  */
 
 /**
- * @ingroup     sys_hashes
+ * @ingroup     sys_hashes_non_crypto
  * @{
  *
  * @file
@@ -28,7 +28,9 @@ extern "C" {
 #endif
 
 /**
- * @brief djb2
+ * @defgroup sys_hashes_djb2 Bernstein hash djb2
+ * @ingroup sys_hashes_non_crypto
+ * @brief djb2 hash algorithm.
  *
  * HISTORY
  * This algorithm (k=33) was first reported by Dan Bernstein many years
@@ -47,7 +49,9 @@ extern "C" {
 uint32_t djb2_hash(const uint8_t *buf, size_t len);
 
 /**
- * @brief sdbm
+ * @defgroup sys_hashes_sdbm sdbm
+ * @ingroup sys_hashes_non_crypto
+ * @brief sdbm hash algorithm.
  *
  * HISTORY
  * This algorithm was created for sdbm (a public-domain reimplementation
@@ -72,7 +76,9 @@ uint32_t djb2_hash(const uint8_t *buf, size_t len);
 uint32_t sdbm_hash(const uint8_t *buf, size_t len);
 
 /**
- * @brief Kernighan and Ritchie
+ * @defgroup sys_hashes_kr Kernighan and Ritchie
+ * @ingroup sys_hashes_non_crypto
+ * @brief Kernighan and Ritchie hash algorithm.
  *
  * HISTORY
  * This hash function appeared in K&R (1st ed) but at least the reader
@@ -97,7 +103,9 @@ uint32_t sdbm_hash(const uint8_t *buf, size_t len);
 uint32_t kr_hash(const uint8_t *buf, size_t len);
 
 /**
- * @brief Shift, Add, XOR
+ * @defgroup sys_hashes_sax Shift, Add, XOR
+ * @ingroup sys_hashes_non_crypto
+ * @brief Shift, Add, XOR hash algorithm.
  *
  * @param buf input buffer to hash
  * @param len length of buffer
@@ -106,7 +114,9 @@ uint32_t kr_hash(const uint8_t *buf, size_t len);
 uint32_t sax_hash(const uint8_t *buf, size_t len);
 
 /**
- * @brief Donald E. Knuth
+ * @defgroup sys_hashes_dek Donald E. Knuth
+ * @ingroup sys_hashes_non_crypto
+ * @brief Donald E. Knuth hash algorithm.
  *
  * HISTORY
  * Proposed by Donald E. Knuth in The Art Of Computer Programming Vol. 3,
@@ -119,7 +129,9 @@ uint32_t sax_hash(const uint8_t *buf, size_t len);
 uint32_t dek_hash(const uint8_t *buf, size_t len);
 
 /**
- * @brief Fowler–Noll–Vo
+ * @defgroup sys_hashes_fnv Fowler–Noll–Vo
+ * @ingroup sys_hashes_non_crypto
+ * @brief Fowler–Noll–Vo hash algorithm.
  *
  * NOTE
  * For a more fully featured and modern version of this hash, see fnv32.c
@@ -132,7 +144,9 @@ uint32_t fnv_hash(const uint8_t *buf, size_t len);
 
 
 /**
- * @brief Rotating
+ * @defgroup sys_hashes_rotating Rotating
+ * @ingroup sys_hashes_non_crypto
+ * @brief Rotating hash algorithm.
  *
  * found on
  * http://burtleburtle.net/bob/hash/doobs.html
@@ -144,7 +158,9 @@ uint32_t fnv_hash(const uint8_t *buf, size_t len);
 uint32_t rotating_hash(const uint8_t *buf, size_t len);
 
 /**
- * @brief One at a time
+ * @defgroup sys_hashes_one_at_a_time One at a time
+ * @ingroup sys_hashes_non_crypto
+ * @brief One at a time hash algorithm.
  *
  * found on
  * http://burtleburtle.net/bob/hash/doobs.html

sys/include/hashes/cmac.h

@@ -8,7 +8,7 @@
 
 /**
  * @defgroup    sys_hashes_cmac AES_CMAC
- * @ingroup     sys_hashes
+ * @ingroup     sys_hashes_keyed
  * @brief       Implementation of the AES CMAC hashing function
 
  * @{

sys/include/hashes/md5.h

@@ -19,7 +19,7 @@
 
 /**
  * @defgroup    sys_hashes_md5 MD5
- * @ingroup     sys_hashes
+ * @ingroup     sys_hashes_unkeyed
  * @brief       Implementation of the MD5 hashing function
  *
  *  None of this will make any sense unless you're studying RFC 1321 as you

sys/include/hashes/sha1.h

@@ -8,7 +8,7 @@
 
 /**
  * @defgroup    sys_hashes_sha1 SHA-1
- * @ingroup     sys_hashes
+ * @ingroup     sys_hashes_unkeyed
  * @brief       Implementation of the SHA-1 hashing function
 
  * @{

sys/include/hashes/sha256.h

@@ -31,7 +31,9 @@
 
 
 /**
- * @ingroup     sys_hashes
+ * @defgroup    sys_hashes_sha256 SHA-256
+ * @ingroup     sys_hashes_unkeyed
+ * @brief       Implementation of the SHA-256 hashing function
  * @{
  *
  * @file
@@ -52,6 +54,9 @@
 extern "C" {
 #endif
 
+/**
+ * @brief   Length of SHA256 digests in bytes
+ */
 #define SHA256_DIGEST_LENGTH 32
 
 /**

sys/include/hashes/sha3.h

@@ -12,7 +12,9 @@
  */
 
 /**
- * @ingroup     sys_hashes
+ * @defgroup    sys_hashes_sha3 SHA-3
+ * @ingroup     sys_hashes_unkeyed
+ * @brief       Implementation of the SHA-3 hashing function
  * @{
  *
  * @file
@@ -31,8 +33,19 @@
 extern "C" {
 #endif
 
+/**
+ * @brief   Length of SHA256 digests in bytes
+ */
 #define SHA3_256_DIGEST_LENGTH 32
+
+/**
+ * @brief   Length of SHA384 digests in bytes
+ */
 #define SHA3_384_DIGEST_LENGTH 48
+
+/**
+ * @brief   Length of SHA512 digests in bytes
+ */
 #define SHA3_512_DIGEST_LENGTH 64
 
 /**