diff --git a/include/polarssl/error.h b/include/polarssl/error.h
index feba67b..23c0ed7 100644
--- a/include/polarssl/error.h
+++ b/include/polarssl/error.h
@@ -60,7 +60,7 @@
  * CAMELLIA  2  0x0024-0x0026
  * XTEA      1  0x0028-0x0028
  * BASE64    2  0x002A-0x002C
- * OID       1  0x002E-0x002E
+ * OID       1  0x002E-0x002E   0x000B-0x000B
  * PADLOCK   1  0x0030-0x0030
  * DES       1  0x0032-0x0032
  * CTR_DBRG  4  0x0034-0x003A
diff --git a/include/polarssl/oid.h b/include/polarssl/oid.h
index 2470d5e..0c471c5 100644
--- a/include/polarssl/oid.h
+++ b/include/polarssl/oid.h
@@ -44,6 +44,7 @@
 #endif
 
 #define POLARSSL_ERR_OID_NOT_FOUND                         -0x002E  /**< OID is not found. */
+#define POLARSSL_ERR_OID_BUF_TOO_SMALL                     -0x000B  /**< output buffer is too small */
 
 /*
  * Top level OID tuples
@@ -376,7 +377,8 @@
  * \param size      size of the buffer
  * \param oid       OID to translate
  *
- * \return          POLARSSL_ERR_DEBUG_BUF_TOO_SMALL or actual length used
+ * \return          Length of the string written (excluding final NULL) or
+ *                  POLARSSL_ERR_OID_BUF_TO_SMALL in case of error
  */
 int oid_get_numeric_string( char *buf, size_t size, const asn1_buf *oid );
 
diff --git a/include/polarssl/x509.h b/include/polarssl/x509.h
index ad8049a..003154b 100644
--- a/include/polarssl/x509.h
+++ b/include/polarssl/x509.h
@@ -212,6 +212,8 @@
 
 /**
  * \brief          Give an known OID, return its descriptive string.
+ *                 (Deprecated. Use oid_get_extended_key_usage() instead.)
+ *                 Warning: only works for extended_key_usage OIDs!
  *
  * \param oid      buffer containing the oid
  *
@@ -228,8 +230,8 @@
  * \param size     Maximum size of buffer
  * \param oid      Buffer containing the OID
  *
- * \return         The amount of data written to the buffer, or -1 in
- *                 case of an error.
+ * \return         Length of the string written (exluding final NULL) or
+ *                 POLARSSL_ERR_OID_BUF_TO_SMALL in case of error
  */
 int x509_oid_get_numeric_string( char *buf, size_t size, x509_buf *oid );