[doc] Put CRC-16 and generic CRC code in one Doxygen module

.. and add missing API documentation bits

Change-Id: I67119894bcbf8c779426a0272bae4c5ce1fbd1ed

5 files changed, 28 insertions, 11 deletions

diff --git a/include/osmocom/core/crc16.h b/include/osmocom/core/crc16.h
index 52807af4..f2e77e4a 100644
--- a/include/osmocom/core/crc16.h
+++ b/include/osmocom/core/crc16.h
@@ -1,13 +1,16 @@
-/*! \file crc16.h
- * This was copied from the linux kernel and adjusted for our types.
+/*! \addtogroup crc
+ *  @{
+ *  \file crc16.h
+ *  This was copied from the linux kernel and adjusted for our types.
  */
+
 /*
  *	crc16.h - CRC-16 routine
  *
  * Implements the standard CRC-16:
- *   Width 16
- *   Poly  0x8005 (x^16 + x^15 + x^2 + 1)
- *   Init  0
+ * - Width 16
+ * - Poly  0x8005 (x^16 + x^15 + x^2 + 1)
+ * - Init  0
  *
  * Copyright (c) 2005 Ben Gardner <bgardner@wabtec.com>
  *
@@ -25,19 +28,22 @@ extern uint16_t const osmo_crc16_table[256];
 
 extern uint16_t osmo_crc16(uint16_t crc, const uint8_t *buffer, size_t len);
 
+/*! CRC-16 polynome 0x8005 (x^16 + x^15 + x^2 + 1) */
 static inline uint16_t osmo_crc16_byte(uint16_t crc, const uint8_t data)
 {
 	return (crc >> 8) ^ osmo_crc16_table[(crc ^ data) & 0xff];
 }
 
 
-/* CCITT polynome 0x8408. This corresponds to x^0 + x^5 + x^12 */
 
 extern uint16_t const osmo_crc16_ccitt_table[256];
 
 extern uint16_t osmo_crc16_ccitt(uint16_t crc, const uint8_t *buffer, size_t len);
 
+/*! CCITT polynome 0x8408 (x^0 + x^5 + x^12) */
 static inline uint16_t osmo_crc16_ccitt_byte(uint16_t crc, const uint8_t data)
 {
 	return (crc >> 8) ^ osmo_crc16_ccitt_table[(crc ^ data) & 0xff];
 }
+
+/*! @} */
diff --git a/include/osmocom/core/crcXXgen.h.tpl b/include/osmocom/core/crcXXgen.h.tpl
index 2c909f92..823f21f2 100644
--- a/include/osmocom/core/crcXXgen.h.tpl
+++ b/include/osmocom/core/crcXXgen.h.tpl
@@ -22,7 +22,7 @@
 
 #pragma once
 
-/*! \addtogroup crcgen
+/*! \addtogroup crc
  *  @{
  * \file crcXXgen.h.tpl */
 
diff --git a/include/osmocom/core/crcgen.h b/include/osmocom/core/crcgen.h
index d73e6e80..7cfe8699 100644
--- a/include/osmocom/core/crcgen.h
+++ b/include/osmocom/core/crcgen.h
@@ -22,7 +22,7 @@
 
 #pragma once
 
-/*! \defgroup crcgen Osmocom generic CRC routines
+/*! \defgroup crc Osmocom CRC routines
  *  @{
  * \file crcgen.h */
 
diff --git a/src/crc16.c b/src/crc16.c
index b5cb9566..c03c0081 100644
--- a/src/crc16.c
+++ b/src/crc16.c
@@ -1,4 +1,6 @@
-/*! \file crc16.c
+/*! \addtogroup crc
+ *  @{
+ *  \file crc16.c
  * This was copied from the linux kernel and adjusted for our types.
  */
 /*
@@ -46,7 +48,7 @@ uint16_t const osmo_crc16_table[256] = {
 	0x8201, 0x42C0, 0x4380, 0x8341, 0x4100, 0x81C1, 0x8081, 0x4040
 };
 
-/*! compute the CRC-16 for the data buffer
+/*! Compute 16bit CCITT polynome 0x8408 (x^0 + x^5 + x^12) over given buffer.
  *  \param crc[in] previous CRC value
  *  \param buffer[in] data pointer
  *  \param len[in] number of bytes in input \ref buffer
@@ -59,6 +61,7 @@ uint16_t osmo_crc16(uint16_t crc, uint8_t const *buffer, size_t len)
 	return crc;
 }
 
+/*! CRC table for the CCITT CRC-6. The poly is 0x8408 (x^0 + x^5 + x^12) */
 uint16_t const osmo_crc16_ccitt_table[256] = {
 	0x0000, 0x1189, 0x2312, 0x329b, 0x4624, 0x57ad, 0x6536, 0x74bf,
 	0x8c48, 0x9dc1, 0xaf5a, 0xbed3, 0xca6c, 0xdbe5, 0xe97e, 0xf8f7,
@@ -94,9 +97,17 @@ uint16_t const osmo_crc16_ccitt_table[256] = {
 	0x7bc7, 0x6a4e, 0x58d5, 0x495c, 0x3de3, 0x2c6a, 0x1ef1, 0x0f78
 };
 
+
+/*! Compute 16bit CCITT polynome 0x8408 (x^0 + x^5 + x^12) over given buffer.
+ *  \param[in] crc initial value of CRC
+ *  \param[in] buffer pointer to buffer of input data
+ *  \param[in] len length of \a buffer in bytes
+ *  \returns 16bit CRC */
 uint16_t osmo_crc16_ccitt(uint16_t crc, uint8_t const *buffer, size_t len)
 {
 	while (len--)
 		crc = osmo_crc16_ccitt_byte(crc, *buffer++);
 	return crc;
 }
+
+/*! @} */
diff --git a/src/crcXXgen.c.tpl b/src/crcXXgen.c.tpl
index e92a5381..befba4d0 100644
--- a/src/crcXXgen.c.tpl
+++ b/src/crcXXgen.c.tpl
@@ -20,7 +20,7 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
-/*! \addtogroup crcgen
+/*! \addtogroup crc
  *  @{
  *  Osmocom generic CRC routines (for max XX bits poly).
  *