Rework documentation of MD layer

- avoid overuse of generic terms such as "initialize"
- spell out the succession of functions

include/mbedtls/md.h

@@ -115,13 +115,15 @@ const md_info_t *md_info_from_type( md_type_t md_type );
 
 /**
  * \brief           Initialize a md_context (as NONE)
+ *                  This should always be called first.
+ *                  Prepares the context for md_setup() or md_free().
  */
 void md_init( md_context_t *ctx );
 
 /**
- * \brief               Free and clear the message-specific context of ctx.
+ * \brief           Free and clear the internal structures of ctx.
- *                      Freeing ctx itself remains the responsibility of the
+ *                  Can be called at any time after md_init().
- *                      caller.
+ *                  Mandatory once md_setup() has been called.
  */
 void md_free( md_context_t *ctx );
 
@@ -132,38 +134,36 @@ void md_free( md_context_t *ctx );
 #define DEPRECATED
 #endif
 /**
- * \brief          Initialises and fills the message digest context structure
+ * \brief           Select MD to use and allocate internal structures.
- *                 with the appropriate values.
+ *                  Should be called after md_init() or md_free().
+ *                  Makes it necessary to call md_free() later.
  *
  * \deprecated      Superseded by md_setup() in 2.0.0
  *
- * \param ctx      context to initialise. May not be NULL. The
+ * \param ctx       Context to set up.
- *                 digest-specific context (ctx->md_ctx) must be NULL. It will
+ * \param md_info   Message digest to use.
- *                 be allocated, and must be freed using md_free() later.
- * \param md_info  message digest to use.
  *
- * \returns        \c 0 on success, \c POLARSSL_ERR_MD_BAD_INPUT_DATA on
+ * \returns         \c 0 on success,
- *                 parameter failure, \c POLARSSL_ERR_MD_ALLOC_FAILED if
+ *                  \c POLARSSL_ERR_MD_BAD_INPUT_DATA on parameter failure,
- *                 allocation of the digest-specific context failed.
+ *                  \c POLARSSL_ERR_MD_ALLOC_FAILED memory allocation failure.
  */
 int md_init_ctx( md_context_t *ctx, const md_info_t *md_info ) DEPRECATED;
 #undef DEPRECATED
 #endif /* POLARSSL_DEPRECATED_REMOVED */
 
 /**
- * \brief          Initialises and fills the message digest context structure
+ * \brief           Select MD to use and allocate internal structures.
- *                 with the appropriate values.
+ *                  Should be called after md_init() or md_free().
+ *                  Makes it necessary to call md_free() later.
  *
- * \param ctx      context to initialise. May not be NULL. The
+ * \param ctx       Context to set up.
- *                 digest-specific context (ctx->md_ctx) must be NULL. It will
+ * \param md_info   Message digest to use.
- *                 be allocated, and must be freed using md_free() later.
+ * \param hmac      0 to save some meory is HMAC will not be use,
- * \param md_info  message digest to use.
+ *                  non-zero is HMAC is going to be used with this context.
- * \param hmac     non-zero if you want to use this context for hmac too,
- *                 zero otherwise (saves some memory).
  *
- * \returns        \c 0 on success, \c POLARSSL_ERR_MD_BAD_INPUT_DATA on
+ * \returns         \c 0 on success,
- *                 parameter failure, \c POLARSSL_ERR_MD_ALLOC_FAILED if
+ *                  \c POLARSSL_ERR_MD_BAD_INPUT_DATA on parameter failure,
- *                 allocation of the digest-specific context failed.
+ *                  \c POLARSSL_ERR_MD_ALLOC_FAILED memory allocation failure.
  */
 int md_setup( md_context_t *ctx, const md_info_t *md_info, int hmac );
 
@@ -195,7 +195,9 @@ md_type_t md_get_type( const md_info_t *md_info );
 const char *md_get_name( const md_info_t *md_info );
 
 /**
- * \brief          Set-up the given context for a new message digest
+ * \brief           Prepare the context to digest a new message.
+ *                  Generally called after md_setup() or md_finish().
+ *                  Followed by md_update().
  *
  * \param ctx       generic message digest context.
  *
@@ -206,6 +208,8 @@ int md_starts( md_context_t *ctx );
 
 /**
  * \brief           Generic message digest process buffer
+ *                  Called between md_starts() and md_finish().
+ *                  May be called repeatedly.
  *
  * \param ctx       Generic message digest context
  * \param input     buffer holding the  datal
@@ -218,6 +222,8 @@ int md_update( md_context_t *ctx, const unsigned char *input, size_t ilen );
 
 /**
  * \brief           Generic message digest final digest
+ *                  Called after md_update().
+ *                  Usually followed by md_free() or md_starts().
  *
  * \param ctx       Generic message digest context
  * \param output    Generic message digest checksum result
@@ -256,9 +262,10 @@ int md_file( const md_info_t *md_info, const char *path,
              unsigned char *output );
 
 /**
- * \brief          Generic HMAC context setup
+ * \brief           Set HMAC key and prepare to authenticate a new message.
+ *                  Usually called after md_setup() or md_hmac_finish().
  *
- * \param ctx      HMAC context to be initialized
+ * \param ctx       HMAC context
  * \param key       HMAC secret key
  * \param keylen    length of the HMAC key
  *
@@ -269,7 +276,10 @@ int md_hmac_starts( md_context_t *ctx, const unsigned char *key,
                     size_t keylen );
 
 /**
- * \brief          Generic HMAC process buffer
+ * \brief           Generic HMAC process buffer.
+ *                  Called between md_hmac_starts() or md_hmac_reset()
+ *                  and md_hmac_finish().
+ *                  May be called repeatedly.
  *
  * \param ctx       HMAC context
  * \param input     buffer holding the  data
@@ -282,7 +292,10 @@ int md_hmac_update( md_context_t *ctx, const unsigned char *input,
                     size_t ilen );
 
 /**
- * \brief          Generic HMAC final digest
+ * \brief           Output HMAC.
+ *                  Called after md_hmac_update().
+ *                  Usually followed my md_hmac_reset(), md_hmac_starts(),
+ *                  or md_free().
  *
  * \param ctx       HMAC context
  * \param output    Generic HMAC checksum result
@@ -293,7 +306,8 @@ int md_hmac_update( md_context_t *ctx, const unsigned char *input,
 int md_hmac_finish( md_context_t *ctx, unsigned char *output);
 
 /**
- * \brief          Generic HMAC context reset
+ * \brief           Prepare to authenticate a new message with the same key.
+ *                  Called after md_hmac_finish() and before md_hmac_update().
  *
  * \param ctx       HMAC context to be reset
  *