security: fix several inaccuracies in the API doc
Change-Id: Ib60487511863c3125337275bed3433cecd81e1ab
Refs: #4062, #4072
diff --git a/src/security/pib/detail/key-impl.hpp b/src/security/pib/detail/key-impl.hpp
index efc69b2..c889a76 100644
--- a/src/security/pib/detail/key-impl.hpp
+++ b/src/security/pib/detail/key-impl.hpp
@@ -47,13 +47,14 @@
/**
* @brief Create a KeyImpl with @p keyName.
*
- * If the key does not exist in the backend, create it in backend.
+ * If the key does not exist in the backend, it will be added.
+ * If a key with the same name already exists, it will be overwritten.
*
* @param keyName The name of the key.
* @param key The public key to add.
* @param keyLen The length of the key.
* @param pibImpl The Pib backend implementation.
- * @throw Pib::Error a key with the same @p keyName already exists.
+ * @throw std::invalid_argument @p key is invalid.
*/
KeyImpl(const Name& keyName, const uint8_t* key, size_t keyLen, shared_ptr<PibImpl> pibImpl);
@@ -85,7 +86,7 @@
}
/**
- * @brief Get key type
+ * @brief Get key type.
*/
KeyType
getKeyType() const
@@ -94,7 +95,7 @@
}
/**
- * @brief Get public key bits
+ * @brief Get public key bits.
*/
const Buffer&
getPublicKey() const
@@ -108,24 +109,24 @@
* If no default certificate is set before, the new certificate will be set as the default
* certificate of the key.
*
- * If a certificate with the same name (without implicit digest) already exists, overwrite
- * the certificate.
+ * If a certificate with the same name (without implicit digest) already exists, it will
+ * be overwritten.
*
- * @throw std::invalid_argument certificate name does not match key name
+ * @throw std::invalid_argument the certificate name does not match the key name.
*/
void
addCertificate(const v2::Certificate& certificate);
/**
- * @brief Remove a certificate with @p certName
- * @throw std::invalid_argument @p certName does not match key name
+ * @brief Remove a certificate with @p certName.
+ * @throw std::invalid_argument @p certName does not match the key name.
*/
void
removeCertificate(const Name& certName);
/**
- * @brief Get a certificate with @p certName
- * @throw std::invalid_argument @p certName does not match key name
+ * @brief Get a certificate with @p certName.
+ * @throw std::invalid_argument @p certName does not match the key name.
* @throw Pib::Error the certificate does not exist.
*/
v2::Certificate
@@ -138,8 +139,8 @@
getCertificates() const;
/**
- * @brief Set an existing one with @p certName as the default certificate
- * @throw std::invalid_argument @p certName does not match key name
+ * @brief Set an existing certificate with name @p certName as the default certificate.
+ * @throw std::invalid_argument @p certName does not match the key name.
* @throw Pib::Error the certificate does not exist.
* @return the default certificate
*/
@@ -147,16 +148,19 @@
setDefaultCertificate(const Name& certName);
/**
- * @brief Add @p certificate and set it as the default certificate of the key
- * @throw std::invalid_argument @p certificate does not match key name
- * @throw Pib::Error the certificate with the same name already exists.
+ * @brief Add @p certificate and set it as the default certificate for this key.
+ *
+ * If a certificate with the same name (without implicit digest) already exists, it will
+ * be overwritten.
+ *
+ * @throw std::invalid_argument @p certificate does not match the key name.
* @return the default certificate
*/
const v2::Certificate&
setDefaultCertificate(const v2::Certificate& certificate);
/**
- * @brief Get the default certificate for this Key.
+ * @brief Get the default certificate for this key.
* @throw Pib::Error the default certificate does not exist.
*/
const v2::Certificate&