Merge pull request #10846 from bulislaw/crc_doxy

MbedCRC doxygen fixes

Author: 0xc0170

drivers/MbedCRC.h

@@ -23,7 +23,7 @@
 #include "platform/SingletonPtr.h"
 #include "platform/PlatformMutex.h"
 
-/* This is invalid warning from the compiler for below section of code
+/* This is an invalid warning from the compiler for the below section of code
 if ((width < 8) && (NULL == _crc_table)) {
     p_crc = (uint32_t)(p_crc << (8 - width));
 }
@@ -43,11 +43,21 @@ namespace mbed {
 /** \addtogroup drivers */
 /** @{*/
 
-/** CRC object provides CRC generation through hardware/software
+extern SingletonPtr<PlatformMutex> mbed_crc_mutex;
+
+/** CRC object provides CRC generation through hardware or software
+ *
+ *  CRC sums can be generated using three different methods: hardware, software ROM tables
+ *  and bitwise computation. The mode used is selected automatically based on required
+ *  polynomial and hardware capabilities. Any polynomial in standard form (`x^3 + x + 1`)
+ *  can be used for computation, but custom ones can affect the performance.
  *
- *  ROM polynomial tables for supported polynomials (:: crc_polynomial_t) will be used for
- *  software CRC computation, if ROM tables are not available then CRC is computed runtime
- *  bit by bit for all data input.
+ *  First choice is the hardware mode. The supported polynomials are hardware specific, and
+ *  you need to consult your MCU manual to discover them. Next, ROM polynomial tables
+ *  are tried (you can find list of supported polynomials here ::crc_polynomial). If the selected
+ *  configuration is supported, it will accelerate the software computations. If ROM tables
+ *  are not available for the selected polynomial, then CRC is computed at run time bit by bit
+ *  for all data input.
  *  @note Synchronization level: Thread safe
  *
  *  @tparam  polynomial CRC polynomial value in hex
@@ -93,9 +103,6 @@ namespace mbed {
  * @endcode
  * @ingroup drivers
  */
-
-extern SingletonPtr<PlatformMutex> mbed_crc_mutex;
-
 template <uint32_t polynomial = POLY_32BIT_ANSI, uint8_t width = 32>
 class MbedCRC {
 

hal/crc_api.h

@@ -28,13 +28,13 @@
  * Different polynomial values supported
  */
 typedef enum crc_polynomial {
-    POLY_OTHER       = 0,
-    POLY_8BIT_CCITT  = 0x07,       // x8+x2+x+1
-    POLY_7BIT_SD     = 0x9,        // x7+x3+1;
-    POLY_16BIT_CCITT = 0x1021,     // x16+x12+x5+1
-    POLY_16BIT_IBM   = 0x8005,     // x16+x15+x2+1
-    POLY_32BIT_ANSI  = 0x04C11DB7, // x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1
-    POLY_32BIT_REV_ANSI = 0xEDB88320
+    POLY_OTHER       = 0,            ///< Custom polynomial
+    POLY_8BIT_CCITT  = 0x07,         ///< x8+x2+x+1
+    POLY_7BIT_SD     = 0x9,          ///< x7+x3+1
+    POLY_16BIT_CCITT = 0x1021,       ///< x16+x12+x5+1
+    POLY_16BIT_IBM   = 0x8005,       ///< x16+x15+x2+1
+    POLY_32BIT_ANSI  = 0x04C11DB7,   ///< x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1
+    POLY_32BIT_REV_ANSI = 0xEDB88320 ///< x31+x30+x29+x27+x26+x24+x23+x21+x20+x19+x15+x9+x8+x5
 } crc_polynomial_t;
 
 typedef struct crc_mbed_config {