diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index f9f9b9b..e208da2 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -1,7 +1,7 @@
 /**
  * \file pk.h
  *
- * \brief Public Key abstraction layer
+ * \brief Public Key cryptography abstraction layer
  *
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
@@ -49,6 +49,9 @@
 #define inline __inline
 #endif
 
+/** \name Error codes */
+/**@{*/
+
 #define MBEDTLS_ERR_PK_ALLOC_FAILED        -0x3F80  /**< Memory allocation failed. */
 #define MBEDTLS_ERR_PK_TYPE_MISMATCH       -0x3F00  /**< Type mismatch, eg attempt to encrypt with an ECDSA key */
 #define MBEDTLS_ERR_PK_BAD_INPUT_DATA      -0x3E80  /**< Bad input parameters to function. */
@@ -64,21 +67,26 @@
 #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980  /**< Unavailable feature, e.g. RSA disabled for RSA key. */
 #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH    -0x3900  /**< The signature is valid but its length is less than expected. */
 
+/**@}*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/** \name Asymmetric cryptography operation contexts */
+/**@{*/
+
 /**
- * \brief          Public key types
+ * \brief          Asymmetric operation context types
  */
 typedef enum {
-    MBEDTLS_PK_NONE=0,
-    MBEDTLS_PK_RSA,
-    MBEDTLS_PK_ECKEY,
-    MBEDTLS_PK_ECKEY_DH,
-    MBEDTLS_PK_ECDSA,
-    MBEDTLS_PK_RSA_ALT,
-    MBEDTLS_PK_RSASSA_PSS,
+    MBEDTLS_PK_NONE=0,          /**< Unused context object */
+    MBEDTLS_PK_RSA,             /**< RSA key pair (normal software implementation) with PKCS#1 v1.5 or PSS context */
+    MBEDTLS_PK_ECKEY,           /**< ECC key pair with ECDSA context */
+    MBEDTLS_PK_ECKEY_DH,        /**< ECC key pair with ECDH context */
+    MBEDTLS_PK_ECDSA,           /**< ECC key pair with ECDSA context */
+    MBEDTLS_PK_RSA_ALT,         /**< RSA (alternative implementation) */
+    MBEDTLS_PK_RSASSA_PSS,      /**< RSA key pair; same context as MBEDTLS_PK_RSA, but used to represent keys with the algorithm identifier id-RSASSA-PSS */
 } mbedtls_pk_type_t;
 
 /**
@@ -116,17 +124,17 @@
 #define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
 
 /**
- * \brief           Public key information and operations
+ * \brief           Key pair information and operations
  */
 typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
 
 /**
- * \brief           Public key container
+ * \brief           Key pair container
  */
 typedef struct
 {
-    const mbedtls_pk_info_t *   pk_info; /**< Public key informations        */
-    void *                      pk_ctx;  /**< Underlying public key context  */
+    const mbedtls_pk_info_t *   pk_info; /**< Algorithm information          */
+    void *                      pk_ctx;  /**< Underlying key pair context */
 } mbedtls_pk_context;
 
 #if defined(MBEDTLS_RSA_C)
@@ -134,7 +142,8 @@
  * Quick access to an RSA context inside a PK context.
  *
  * \warning You must make sure the PK context actually holds an RSA context
- * before using this function!
+ * before using this function! This function is only valid if
+ * `pk_can_do(&pk, MBEDTLS_PK_RSA)` is true.
  */
 static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
 {
@@ -147,7 +156,8 @@
  * Quick access to an EC context inside a PK context.
  *
  * \warning You must make sure the PK context actually holds an EC context
- * before using this function!
+ * before using this function! This function is only valid if
+ * `pk_can_do(&pk, MBEDTLS_PK_ECKEY)` is true.
  */
 static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
 {
@@ -170,10 +180,17 @@
 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
 
 /**
- * \brief           Return information associated with the given PK type
+ * \brief           Return default information associated with the given PK type
  *
  * \param pk_type   PK type to search for.
  *
+ * \note            Different PK objects with the same type may have different
+ *                  information. This function returns the information needed
+ *                  to create a object with the default implementation
+ *                  for the given PK operation type (rsa module for an RSA
+ *                  context, ecdh module for an ECDH context, ecdsa module for
+ *                  an ECDSA context).
+ *
  * \return          The PK info associated with the type or NULL if not found.
  */
 const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
@@ -199,7 +216,7 @@
  *                  MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,
  *                  MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
  *
- * \note            For contexts holding an RSA-alt key, use
+ * \note            For contexts holding an RSA-alt key pair, use
  *                  \c mbedtls_pk_setup_rsa_alt() instead.
  */
 int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
@@ -209,7 +226,7 @@
  * \brief           Initialize an RSA-alt context
  *
  * \param ctx       Context to initialize. Must be empty (type NONE).
- * \param key       RSA key pointer
+ * \param key       RSA key pair pointer
  * \param decrypt_func  Decryption function
  * \param sign_func     Signing function
  * \param key_len_func  Function returning key length in bytes
@@ -238,6 +255,11 @@
  * \brief           Get the length in bytes of the underlying key
  * \param ctx       Context to use
  *
+ * \note            This returns the minimum number of bytes required to
+ *                  store the part of the key that defines its size (modulus
+ *                  for RSA, coordinate for ECC). The way the key is stored
+ *                  in the context may have a different size.
+ *
  * \return          Key length in bytes, or 0 on error
  */
 static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
@@ -246,13 +268,24 @@
 }
 
 /**
- * \brief           Tell if a context can do the operation given by type
+ * \brief           Tell if a context can do the operations given by type
+ *
+ * \note            This function can be used to identify the type of key
+ *                  (e.g. RSA vs ECC), and a superset of permitted
+ *                  operations. It is possible that this function returns
+ *                  true but some operations are not allowed. For example
+ *                  this function always returns true if ctx is an RSA
+ *                  context and type is MBEDTLS_PK_RSA, but the key may
+ *                  be restricted to any subset of operations among signature,
+ *                  verification, encryption and decryption. To determine
+ *                  which operations a key allow, attempt the operation and
+ *                  check the return status.
  *
  * \param ctx       Context to test
  * \param type      Target type
  *
- * \return          0 if context can't do the operations,
- *                  1 otherwise.
+ * \return          1 if context can do the operations,
+ *                  0 otherwise.
  */
 int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
 
@@ -269,7 +302,7 @@
  * \return          0 on success (signature is valid),
  *                  MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
  *                  valid but its actual length is less than sig_len,
- *                  or a specific error code.
+ *                  or a type-specific error code.
  *
  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
  *                  Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
@@ -302,7 +335,7 @@
  *                  used for this type of signatures,
  *                  MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
  *                  valid but its actual length is less than sig_len,
- *                  or a specific error code.
+ *                  or a type-specific error code.
  *
  * \note            If hash_len is 0, then the length associated with md_alg
  *                  is used instead, or an error returned if it is invalid.
@@ -330,7 +363,7 @@
  * \param f_rng     RNG function
  * \param p_rng     RNG parameter
  *
- * \return          0 on success, or a specific error code.
+ * \return          0 on success, or a type-specific error code.
  *
  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
  *                  There is no interface in the PK module to make RSASSA-PSS
@@ -361,7 +394,7 @@
  *
  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
  *
- * \return          0 on success, or a specific error code.
+ * \return          0 on success, or a type-specific error code.
  */
 int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,
                 const unsigned char *input, size_t ilen,
@@ -382,7 +415,7 @@
  *
  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
  *
- * \return          0 on success, or a specific error code.
+ * \return          0 on success, or a type-specific error code.
  */
 int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,
                 const unsigned char *input, size_t ilen,
@@ -395,7 +428,12 @@
  * \param pub       Context holding a public key.
  * \param prv       Context holding a private (and public) key.
  *
- * \return          0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
+ * \return          * 0 on success.
+ *                  * MBEDTLS_ERR_PK_BAD_INPUT_DATA if one of the contexts
+ *                    is ill-formed.
+ *                  * MBEDTLS_ERR_PK_TYPE_MISMATCH if the contexts cannot
+ *                    represent keys of the same type.
+ *                  * Or a type-specific error code.
  */
 int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
 
@@ -405,7 +443,11 @@
  * \param ctx       Context to use
  * \param items     Place to write debug items
  *
- * \return          0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
+ * \return          * 0 on success.
+ *                  * MBEDTLS_ERR_PK_BAD_INPUT_DATA if the context is ill-formed.
+ *                  * MBEDTLS_ERR_PK_TYPE_MISMATCH if the context does not
+ *                    support exporting debug information.
+ *                  * Or a type-specific error code.
  */
 int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items );
 
@@ -427,6 +469,9 @@
  */
 mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
 
+/**@}*/
+
+
 #if defined(MBEDTLS_PK_PARSE_C)
 /** \ingroup pk_module */
 /**
@@ -511,7 +556,12 @@
 #endif /* MBEDTLS_FS_IO */
 #endif /* MBEDTLS_PK_PARSE_C */
 
+
+
 #if defined(MBEDTLS_PK_WRITE_C)
+/** \name Key pair serialization */
+/**@{*/
+
 /**
  * \brief           Write a private key to a PKCS#1 or SEC1 DER structure
  *                  Note: data is written at the end of the buffer! Use the
@@ -565,11 +615,13 @@
  */
 int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
 #endif /* MBEDTLS_PEM_WRITE_C */
+/**@}*/
 #endif /* MBEDTLS_PK_WRITE_C */
 
-/*
- * WARNING: Low-level functions. You probably do not want to use these unless
- *          you are certain you do ;)
+/** \name Low-level functions */
+/**@{*/
+/**
+ * \warning You probably do not want to use these unless you are certain you do ;)
  */
 
 #if defined(MBEDTLS_PK_PARSE_C)
@@ -609,6 +661,8 @@
 int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
 #endif
 
+/**@}*/
+
 #ifdef __cplusplus
 }
 #endif