Improve docs for named bitstrings and their usage

Author: Andres Amaya Garcia

include/mbedtls/asn1write.h

@@ -283,19 +283,21 @@ int mbedtls_asn1_write_bitstring( unsigned char **p, unsigned char *start,
                                   const unsigned char *buf, size_t bits );
 
 /**
- * \brief           Write a named bitstring tag (MBEDTLS_ASN1_BIT_STRING) and
- *                  value in ASN.1 format
- *                  Note: function works backwards in data buffer
+ * \brief           This function writes a named bitstring tag
+ *                  (#MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format.
  *
- *                  As stated in RFC5280 Appending B, trailing zeroes are
+ *                  As stated in RFC 5280 Appendix B, trailing zeroes are
  *                  omitted when encoding named bitstrings in DER.
  *
- * \param p         Reference to current position pointer.
- * \param start     Start of the buffer (for bounds-checking).
- * \param buf       The bitstring.
+ * \note            This function works backwards within the data buffer.
+ *
+ * \param p         The reference to the current position pointer.
+ * \param start     The start of the buffer which is used for bounds-checking.
+ * \param buf       The bitstring to write.
  * \param bits      The total number of bits in the bitstring.
  *
- * \return          The length written or a negative error code.
+ * \return          The number of bytes written to \p p on success.
+ * \return          A negative error code on failure.
  */
 int mbedtls_asn1_write_named_bitstring( unsigned char **p,
                                         unsigned char *start,

include/mbedtls/x509_csr.h

@@ -205,6 +205,14 @@ void mbedtls_x509write_csr_set_md_alg( mbedtls_x509write_csr *ctx, mbedtls_md_ty
  * \param key_usage key usage flags to set
  *
  * \return          0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
+ *
+ * \note            The <code>decipherOnly</code> flag from the Key Usage
+ *                  extension is represented by bit 8 (i.e.
+ *                  <code>0x8000</code>), which cannot typically be represented
+ *                  in an unsigned char. Therefore, the flag
+ *                  <code>decipherOnly</code> (i.e.
+ *                  #MBEDTLS_X509_KU_DECIPHER_ONLY) cannot be set using this
+ *                  function.
  */
 int mbedtls_x509write_csr_set_key_usage( mbedtls_x509write_csr *ctx, unsigned char key_usage );