Improve header docs and rename parameter
Signed-off-by: David Horstmann <david.horstmann@arm.com>
diff --git a/include/mbedtls/oid.h b/include/mbedtls/oid.h
index 1284aa9..49f4af5 100644
--- a/include/mbedtls/oid.h
+++ b/include/mbedtls/oid.h
@@ -470,15 +470,20 @@
* \brief Translate a string containing a numeric representation
* of an ASN.1 OID into its encoded form
* (e.g. "1.2.840.113549" into "\x2A\x86\x48\x86\xF7\x0D")
+ * On success, this function allocates oid->buf from the
+ * heap. It must be free'd by the caller.
*
- * \param buf buffer to put representation in
- * \param size size of the buffer
- * \param oid OID to translate
+ * \param oid mbedtls_asn1_buf to populate with the DER-encoded OID
+ * \param oid_str string representation of the OID to parse
+ * \param size length of the OID string
*
- * \return Length of the string written (excluding final NULL) or
- * MBEDTLS_ERR_OID_BUF_TOO_SMALL in case of error
+ * \return 0 if successful
+ * \return #MBEDTLS_ERR_ASN1_INVALID_DATA if oid_str does not
+ * represent a valid OID
+ * \return #MBEDTLS_ERR_ASN1_ALLOC_FAILED if the function fails to
+ * allocate oid->buf
*/
-int mbedtls_oid_from_numeric_string(mbedtls_asn1_buf *oid, const char *buf, size_t size);
+int mbedtls_oid_from_numeric_string(mbedtls_asn1_buf *oid, const char *oid_str, size_t size);
/**
* \brief Translate an X.509 extension OID into local values