Documentation fixes

Rephrase documentation of the SAN to make it clearer.

include/mbedtls/x509_crt.h

@@ -78,7 +78,7 @@ typedef struct mbedtls_x509_crt
     mbedtls_x509_buf v3_ext;            /**< Optional X.509 v3 extensions.  */
     mbedtls_x509_sequence subject_alt_names;    /**< Optional list of raw entries of Subject Alternative Names extension (currently only dNSName and OtherName are listed). */
 
-    mbedtls_x509_sequence certificate_policies; /**< Optional list of certificate policies (Only anyPolicy supported). */
+    mbedtls_x509_sequence certificate_policies; /**< Optional list of certificate policies (Only anyPolicy is printed and enforced, however the rest of the policies are still listed). */
 
     int ext_types;              /**< Bit string containing detected and parsed extensions */
     int ca_istrue;              /**< Optional Basic Constraint extension value: 1 if this certificate belongs to a CA, 0 otherwise. */
@@ -398,31 +398,31 @@ int mbedtls_x509_crt_parse_path( mbedtls_x509_crt *chain, const char *path );
 
 #endif /* MBEDTLS_FS_IO */
 /**
- * \brief          Parses a subject alternative name item
+ * \brief          This function parses an item in the SubjectAlternativeNames
- *                 to an identified structure;
+ *                 extension.
  *
  * \param san_buf  The buffer holding the raw data item of the subject
  *                 alternative name.
  * \param san      The target structure to populate with the parsed presentation
  *                 of the subject alternative name encoded in \p san_raw.
  *
- * \note           Only "dnsName" and "otherName" of type hardware_module_name,
+ * \note           Only "dnsName" and "otherName" of type hardware_module_name
  *                 as defined in RFC 4180 is supported.
  *
  * \note           This function should be called on a single raw data of
  *                 subject alternative name. For example, after successful
  *                 certificate parsing, one must iterate on every item in the
- *                 \p crt->subject_alt_names sequence, and send it as parameter
+ *                 \p crt->subject_alt_names sequence, and pass it to
- *                 to this function.
+ *                 this function.
  *
- * \note           The target structure contains pointers to the raw data of the
+ * \warning        The target structure contains pointers to the raw data of the
  *                 parsed certificate, and its lifetime is restricted by the
  *                 lifetime of the certificate.
  *
  * \return         \c 0 on success
  * \return         #MBEDTLS_ERR_X509_FEATURE_UNAVAILABLE for an unsupported
- *                 SAN type
+ *                 SAN type.
- * \return         Negative value for any other failure.
+ * \return         Another negative value for any other failure.
  */
 int mbedtls_x509_parse_subject_alt_name( const mbedtls_x509_buf *san_buf,
                                          mbedtls_x509_subject_alternative_name *san );

library/x509_crt.c

@@ -618,8 +618,8 @@ static int x509_get_ext_key_usage( unsigned char **p,
  *      nameAssigner            [0]     DirectoryString OPTIONAL,
  *      partyName               [1]     DirectoryString }
  *
- * NOTE: we only parse and use dNSName at this point,
+ * NOTE: we list all types, but only use dNSName and otherName
- * and otherName of type HwModuleName, as defined in RFC 4108.
+ * of type HwModuleName, as defined in RFC 4108, at this point.
  */
 static int x509_get_subject_alt_name( unsigned char **p,
                                       const unsigned char *end,