Update sha256.h

Minor documentation improvements:
*Standardized file brief description.
*Separated return statements.
*Reordered tags within documentation blocks so that params and returns are last in block.
*Removed bullets from parameter descriptions.

include/mbedtls/sha256.h

@@ -1,7 +1,10 @@
 /**
  * \file sha256.h
  *
- * \brief The SHA-224 and SHA-256 cryptographic hash function.
+ * \brief This file contains SHA-224 and SHA-256 definitions and functions.
+ *
+ * The Secure Hash Algorithms 224 and 256 (SHA-224 and SHA-256) cryptographic
+ * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
  */
 /*
  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -55,9 +58,8 @@ typedef struct
     uint32_t total[2];          /*!< The number of Bytes processed.  */
     uint32_t state[8];          /*!< The intermediate digest state.  */
     unsigned char buffer[64];   /*!< The data block being processed. */
-    int is224;                  /*!< Determines which function to use.
+    int is224;                  /*!< Determines which function to use:
-                                     <ul><li>0: Use SHA-256.</li>
+                                     0: Use SHA-256, or 1: Use SHA-224. */
-                                     <li>1: Use SHA-224.</li></ul> */
 }
 mbedtls_sha256_context;
 
@@ -89,9 +91,8 @@ void mbedtls_sha256_clone( mbedtls_sha256_context *dst,
  *                 calculation.
  *
  * \param ctx      The context to initialize.
- * \param is224    Determines which function to use.
+ * \param is224    Determines which function to use:
- *                 <ul><li>0: Use SHA-256.</li>
+ *                 0: Use SHA-256, or 1: Use SHA-224.
- *                 <li>1: Use SHA-224.</li></ul>
  *
  * \return         \c 0 on success.
  */
@@ -101,9 +102,9 @@ int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
  * \brief          This function feeds an input buffer into an ongoing
  *                 SHA-256 checksum calculation.
  *
- * \param ctx      SHA-256 context
+ * \param ctx      The SHA-256 context to initialize.
- * \param input    buffer holding the data
+ * \param input    The buffer holding the data.
- * \param ilen     length of the input data
+ * \param ilen     The length of the input data.
  *
  * \return         \c 0 on success.
  */
@@ -143,14 +144,15 @@ int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief          This function starts a SHA-256 checksum calculation.
+ * \brief          This function starts a SHA-224 or SHA-256 checksum
+ *                 calculation.
+ *
  *
  * \deprecated     Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
  *
- * \param ctx      The SHA-256 context to initialize.
+ * \param ctx      The context to initialize.
- * \param is224    Determines which function to use.
+ * \param is224    Determines which function to use:
- *                 <ul><li>0: Use SHA-256.</li>
+ *                 0: Use SHA-256, or 1: Use SHA-224.
- *                 <li>1: Use SHA-224.</li></ul>
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx,
                                                int is224 );
@@ -176,7 +178,7 @@ MBEDTLS_DEPRECATED void mbedtls_sha256_update( mbedtls_sha256_context *ctx,
  * \deprecated     Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
  *
  * \param ctx      The SHA-256 context.
- * \param output   The SHA-224or SHA-256 checksum result.
+ * \param output   The SHA-224 or SHA-256 checksum result.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx,
                                                unsigned char output[32] );
@@ -221,9 +223,8 @@ extern "C" {
  * \param input    The buffer holding the input data.
  * \param ilen     The length of the input data.
  * \param output   The SHA-224 or SHA-256 checksum result.
- * \param is224    Determines which function to use.
+ * \param is224    Determines which function to use:
- *                 <ul><li>0: Use SHA-256.</li>
+ *                 0: Use SHA-256, or 1: Use SHA-224.
- *                 <li>1: Use SHA-224.</li></ul>
  */
 int mbedtls_sha256_ret( const unsigned char *input,
                         size_t ilen,
@@ -252,9 +253,8 @@ int mbedtls_sha256_ret( const unsigned char *input,
  * \param input    The buffer holding the data.
  * \param ilen     The length of the input data.
  * \param output   The SHA-224 or SHA-256 checksum result.
- * \param is224    Determines which function to use.
+ * \param is224    Determines which function to use:
- *                 <ul><li>0: Use SHA-256.</li>
+ *                 0: Use SHA-256, or 1: Use SHA-224.
- *                 <li>1: Use SHA-224.</li></ul>
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input,
                                         size_t ilen,
@@ -267,7 +267,8 @@ MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input,
 /**
  * \brief          The SHA-224 and SHA-256 checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_sha256_self_test( int verbose );