Improve documentation of mbedtls_pem_write_buffer()
In particular, mention that it supports overlapping input and
output buffers.
diff --git a/include/mbedtls/pem.h b/include/mbedtls/pem.h
index a29e9ce..b37f987 100644
--- a/include/mbedtls/pem.h
+++ b/include/mbedtls/pem.h
@@ -112,17 +112,27 @@
* \brief Write a buffer of PEM information from a DER encoded
* buffer.
*
- * \param header header string to write
- * \param footer footer string to write
- * \param der_data DER data to write
- * \param der_len length of the DER data
- * \param buf buffer to write to
- * \param buf_len length of output buffer
- * \param olen total length written / required (if buf_len is not enough)
+ * \param header The header string to write.
+ * \param footer The footer string to write.
+ * \param der_data The DER data to encode.
+ * \param der_len The length of the DER data \p der_data in Bytes.
+ * \param buf The buffer to write to.
+ * \param buf_len The length of the output buffer \p buf in Bytes.
+ * \param olen The address at which to store the total length written
+ * or required (if \p buf_len is not enough).
*
- * \return 0 on success, or a specific PEM or BASE64 error code. On
- * MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL olen is the required
- * size.
+ * \note You may pass \c NULL for \p buf and \c 0 for \p buf_len
+ * to request the length of the resulting PEM buffer in
+ * `*olen`.
+ *
+ * \note This function may be called with overlapping \p der_data
+ * and \p buf buffers.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL if \p buf isn't large
+ * enough to hold the PEM buffer. In this case, `*olen` holds
+ * the required minimum size of \p buf.
+ * \return Another PEM or BASE64 error code on other kinds of failure.
*/
int mbedtls_pem_write_buffer( const char *header, const char *footer,
const unsigned char *der_data, size_t der_len,
