diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index 4f1b06f..f1ce746 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -202,13 +202,19 @@
 const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
 
 /**
- * \brief           Initialize a mbedtls_pk_context (as NONE)
+ * \brief           Initialize a #mbedtls_pk_context (as NONE).
+ *
+ * \param ctx       The context to initialize.
+ *                  This must not be \c NULL.
  */
 void mbedtls_pk_init( mbedtls_pk_context *ctx );
 
 /**
  * \brief           Free a mbedtls_pk_context
  *
+ * \param ctx       The context to clear. It must have been initialized.
+ *                  If this is \c NULL, this function does nothing.
+ *
  * \note            For contexts that have been set up with
  *                  mbedtls_pk_setup_opaque(), this does not free the underlying
  *                  key slot and you still need to call psa_destroy_key()
@@ -219,11 +225,17 @@
 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
 /**
  * \brief           Initialize a restart context
+ *
+ * \param ctx       The context to initialize.
+ *                  This must not be \c NULL.
  */
 void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
 
 /**
  * \brief           Free the components of a restart context
+ *
+ * \param ctx       The context to clear. It must have been initialized.
+ *                  If this is \c NULL, this function does nothing.
  */
 void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
@@ -232,7 +244,8 @@
  * \brief           Initialize a PK context with the information given
  *                  and allocates the type-specific PK subcontext.
  *
- * \param ctx       Context to initialize. Must be empty (type NONE).
+ * \param ctx       Context to initialize. It must not have been set
+ *                  up yet (type #MBEDTLS_PK_NONE).
  * \param info      Information to use
  *
  * \return          0 on success,
@@ -280,7 +293,8 @@
 /**
  * \brief           Initialize an RSA-alt context
  *
- * \param ctx       Context to initialize. Must be empty (type NONE).
+ * \param ctx       Context to initialize. It must not have been set
+ *                  up yet (type #MBEDTLS_PK_NONE).
  * \param key       RSA key pointer
  * \param decrypt_func  Decryption function
  * \param sign_func     Signing function
@@ -300,7 +314,7 @@
 /**
  * \brief           Get the size in bits of the underlying key
  *
- * \param ctx       Context to use
+ * \param ctx       The context to query. It must have been initialized.
  *
  * \return          Key size in bits, or 0 on error
  */
@@ -308,7 +322,8 @@
 
 /**
  * \brief           Get the length in bytes of the underlying key
- * \param ctx       Context to use
+ *
+ * \param ctx       The context to query. It must have been initialized.
  *
  * \return          Key length in bytes, or 0 on error
  */
@@ -320,18 +335,21 @@
 /**
  * \brief           Tell if a context can do the operation given by type
  *
- * \param ctx       Context to test
- * \param type      Target type
+ * \param ctx       The context to query. It must have been initialized.
+ * \param type      The desired type.
  *
- * \return          0 if context can't do the operations,
- *                  1 otherwise.
+ * \return          1 if the context can do operations on the given type.
+ * \return          0 if the context cannot do the operations on the given
+ *                  type. This is always the case for a context that has
+ *                  been initialized but not set up, or that has been
+ *                  cleared with mbedtls_pk_free().
  */
 int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
 
 /**
  * \brief           Verify signature (including padding if relevant).
  *
- * \param ctx       PK context to use
+ * \param ctx       The PK context to use. It must have been set up.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -364,7 +382,7 @@
  *                  \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
  *                  operations. For RSA, same as \c mbedtls_pk_verify().
  *
- * \param ctx       PK context to use
+ * \param ctx       The PK context to use. It must have been set up.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -388,7 +406,7 @@
  *
  * \param type      Signature type (inc. possible padding type) to verify
  * \param options   Pointer to type-specific options, or NULL
- * \param ctx       PK context to use
+ * \param ctx       The PK context to use. It must have been set up.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -419,7 +437,8 @@
 /**
  * \brief           Make signature, including padding if relevant.
  *
- * \param ctx       PK context to use - must hold a private key
+ * \param ctx       The PK context to use. It must have been set up
+ *                  with a private key.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -453,7 +472,8 @@
  *                  \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
  *                  operations. For RSA, same as \c mbedtls_pk_sign().
  *
- * \param ctx       PK context to use - must hold a private key
+ * \param ctx       The PK context to use. It must have been set up
+ *                  with a private key.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -477,7 +497,8 @@
 /**
  * \brief           Decrypt message (including padding if relevant).
  *
- * \param ctx       PK context to use - must hold a private key
+ * \param ctx       The PK context to use. It must have been set up
+ *                  with a private key.
  * \param input     Input to decrypt
  * \param ilen      Input size
  * \param output    Decrypted output
@@ -498,7 +519,7 @@
 /**
  * \brief           Encrypt message (including padding if relevant).
  *
- * \param ctx       PK context to use
+ * \param ctx       The PK context to use. It must have been set up.
  * \param input     Message to encrypt
  * \param ilen      Message size
  * \param output    Encrypted output
@@ -533,7 +554,7 @@
 /**
  * \brief           Export debug information
  *
- * \param ctx       Context to use
+ * \param ctx       The PK context to use. It must have been initialized.
  * \param items     Place to write debug items
  *
  * \return          0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
@@ -543,7 +564,7 @@
 /**
  * \brief           Access the type name
  *
- * \param ctx       Context to use
+ * \param ctx       The PK context to use. It must have been initialized.
  *
  * \return          Type name on success, or "invalid PK"
  */
@@ -552,9 +573,10 @@
 /**
  * \brief           Get the key type
  *
- * \param ctx       Context to use
+ * \param ctx       The PK context to use. It must have been initialized.
  *
- * \return          Type on success, or MBEDTLS_PK_NONE
+ * \return          Type on success.
+ * \return          #MBEDTLS_PK_NONE for a context that has not been set up.
  */
 mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
 
@@ -563,12 +585,22 @@
 /**
  * \brief           Parse a private key in PEM or DER format
  *
- * \param ctx       key to be initialized
- * \param key       input buffer
- * \param keylen    size of the buffer
- *                  (including the terminating null byte for PEM data)
- * \param pwd       password for decryption (optional)
- * \param pwdlen    size of the password
+ * \param ctx       The PK context to fill. It must have been initialized
+ *                  but not set up.
+ * \param key       Input buffer to parse.
+ *                  The buffer must contain the input exactly, with no
+ *                  extra trailing material. For PEM, the buffer must
+ *                  contain a null-terminated string.
+ * \param keylen    Size of \b key in bytes.
+ *                  For PEM data, this includes the terminating null byte,
+ *                  so \p keylen must be equal to `strlen(key) + 1`.
+ * \param pwd       Optional password for decryption.
+ *                  Pass \c NULL if expecting a non-encrypted key.
+ *                  Pass a string of \p pwdlen bytes if expecting an encrypted
+ *                  key; a non-encrypted key will also be accepted.
+ *                  The empty password is not supported.
+ * \param pwdlen    Size of the password in bytes.
+ *                  Ignored if \p pwd is \c NULL.
  *
  * \note            On entry, ctx must be empty, either freshly initialised
  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
@@ -586,10 +618,15 @@
 /**
  * \brief           Parse a public key in PEM or DER format
  *
- * \param ctx       key to be initialized
- * \param key       input buffer
- * \param keylen    size of the buffer
- *                  (including the terminating null byte for PEM data)
+ * \param ctx       The PK context to fill. It must have been initialized
+ *                  but not set up.
+ * \param key       Input buffer to parse.
+ *                  The buffer must contain the input exactly, with no
+ *                  extra trailing material. For PEM, the buffer must
+ *                  contain a null-terminated string.
+ * \param keylen    Size of \b key in bytes.
+ *                  For PEM data, this includes the terminating null byte,
+ *                  so \p keylen must be equal to `strlen(key) + 1`.
  *
  * \note            On entry, ctx must be empty, either freshly initialised
  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
@@ -607,9 +644,14 @@
 /**
  * \brief           Load and parse a private key
  *
- * \param ctx       key to be initialized
+ * \param ctx       The PK context to fill. It must have been initialized
+ *                  but not set up.
  * \param path      filename to read the private key from
- * \param password  password to decrypt the file (can be NULL)
+ * \param password  Optional password to decrypt the file.
+ *                  Pass \c NULL if expecting a non-encrypted key.
+ *                  Pass a null-terminated string if expecting an encrypted
+ *                  key; a non-encrypted key will also be accepted.
+ *                  The empty password is not supported.
  *
  * \note            On entry, ctx must be empty, either freshly initialised
  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
@@ -626,7 +668,8 @@
 /**
  * \brief           Load and parse a public key
  *
- * \param ctx       key to be initialized
+ * \param ctx       The PK context to fill. It must have been initialized
+ *                  but not set up.
  * \param path      filename to read the public key from
  *
  * \note            On entry, ctx must be empty, either freshly initialised
@@ -649,7 +692,7 @@
  *                        return value to determine where you should start
  *                        using the buffer
  *
- * \param ctx       private to write away
+ * \param ctx       PK context which must contain a valid private key.
  * \param buf       buffer to write to
  * \param size      size of the buffer
  *
@@ -664,7 +707,7 @@
  *                        return value to determine where you should start
  *                        using the buffer
  *
- * \param ctx       public key to write away
+ * \param ctx       PK context which must contain a valid public or private key.
  * \param buf       buffer to write to
  * \param size      size of the buffer
  *
@@ -677,9 +720,10 @@
 /**
  * \brief           Write a public key to a PEM string
  *
- * \param ctx       public key to write away
- * \param buf       buffer to write to
- * \param size      size of the buffer
+ * \param ctx       PK context which must contain a valid public or private key.
+ * \param buf       Buffer to write to. The output includes a
+ *                  terminating null byte.
+ * \param size      Size of the buffer in bytes.
  *
  * \return          0 if successful, or a specific error code
  */
@@ -688,9 +732,10 @@
 /**
  * \brief           Write a private key to a PKCS#1 or SEC1 PEM string
  *
- * \param ctx       private to write away
- * \param buf       buffer to write to
- * \param size      size of the buffer
+ * \param ctx       PK context which must contain a valid private key.
+ * \param buf       Buffer to write to. The output includes a
+ *                  terminating null byte.
+ * \param size      Size of the buffer in bytes.
  *
  * \return          0 if successful, or a specific error code
  */
@@ -709,7 +754,8 @@
  *
  * \param p         the position in the ASN.1 data
  * \param end       end of the buffer
- * \param pk        the key to fill
+ * \param pk        The PK context to fill. It must have been initialized
+ *                  but not set up.
  *
  * \return          0 if successful, or a specific PK error code
  */
@@ -724,7 +770,7 @@
  *
  * \param p         reference to current position pointer
  * \param start     start of the buffer (for bounds-checking)
- * \param key       public key to write away
+ * \param key       PK context which must contain a valid public or private key.
  *
  * \return          the length written or a negative error code
  */