Improve pkcs11 doxygen [ci skip]

3 files changed, 49 insertions, 13 deletions

diff --git a/src/lib/prov/pkcs11/p11_ecc_key.h b/src/lib/prov/pkcs11/p11_ecc_key.h
index 3d10ae85e..8b2ede566 100644
--- a/src/lib/prov/pkcs11/p11_ecc_key.h
+++ b/src/lib/prov/pkcs11/p11_ecc_key.h
@@ -181,12 +181,11 @@ class BOTAN_DLL PKCS11_EC_PrivateKey : public virtual Private_Key,
 
       /**
       * Gets the public_point
-      * @note: the public key must be set using `set_public_point`
-      *        because it is not possible to infer the public key from a PKCS#11 EC private key
+      * @note the public key must be set using `set_public_point`
+      *       because it is not possible to infer the public key from a PKCS#11 EC private key
       * @return the public point of the private key
       * @throws Exception if the public point was not set using set_public_point()
       */
-
       const PointGFp& public_point() const
          {
          if(m_public_key.is_zero())
diff --git a/src/lib/prov/pkcs11/p11_mechanism.h b/src/lib/prov/pkcs11/p11_mechanism.h
index 0f7b6f07c..dde5e5b07 100644
--- a/src/lib/prov/pkcs11/p11_mechanism.h
+++ b/src/lib/prov/pkcs11/p11_mechanism.h
@@ -21,7 +21,7 @@ namespace PKCS11 {
 /**
 * Simple class to build and hold the data for a CK_MECHANISM struct
 * for RSA (encryption/decryption, signature/verification)
-* and EC (ecdsa signature/verification, ecdh key derivation)
+* and EC (ECDSA signature/verification, ECDH key derivation).
 */
 class MechanismWrapper final
    {
@@ -58,14 +58,22 @@ class MechanismWrapper final
       */
       static MechanismWrapper create_ecdh_mechanism(const std::string& params);
 
-      /// Sets the salt for the ECDH mechanism parameters
+      /**
+      * Sets the salt for the ECDH mechanism parameters.
+      * @param salt the salt
+      * @param salt_len size of the salt in bytes
+      */
       inline void set_ecdh_salt(const byte salt[], size_t salt_len)
          {
          m_parameters->ecdh_params.pSharedData = const_cast<byte*>(salt);
          m_parameters->ecdh_params.ulSharedDataLen = salt_len;
          }
 
-      /// Sets the public key of the other party for the ECDH mechanism parameters
+      /**
+      * Sets the public key of the other party for the ECDH mechanism parameters.
+      * @param other_key key of the other party
+      * @param other_key_len size of the key of the other party in bytes
+      */
       inline void set_ecdh_other_key(const byte other_key[], size_t other_key_len)
          {
          m_parameters->ecdh_params.pPublicData = const_cast<byte*>(other_key);
diff --git a/src/lib/prov/pkcs11/p11_object.h b/src/lib/prov/pkcs11/p11_object.h
index 4a6a54b20..dce75ff44 100644
--- a/src/lib/prov/pkcs11/p11_object.h
+++ b/src/lib/prov/pkcs11/p11_object.h
@@ -52,6 +52,7 @@ class BOTAN_DLL AttributeContainer
          return m_attributes;
          }
 
+      /// @return raw attribute data
       inline Attribute* data() const
          {
          return const_cast< Attribute* >(m_attributes.data());
@@ -63,26 +64,51 @@ class BOTAN_DLL AttributeContainer
          return m_attributes.size();
          }
 
-      /// Add a class attribute (CKA_CLASS / AttributeType::Class)
+      /**
+      * Add a class attribute (CKA_CLASS / AttributeType::Class).
+      * @param object_class class attribute to add
+      */
       void add_class(ObjectClass object_class);
 
-      /// Add a string attribute (e.g. CKA_LABEL / AttributeType::Label)
+      /**
+      * Add a string attribute (e.g. CKA_LABEL / AttributeType::Label).
+      * @param attribute attribute type
+      * @param value string value to add
+      */
       void add_string(AttributeType attribute, const std::string& value);
 
-      /// Add a binary attribute (e.g. CKA_ID / AttributeType::Id)
+      /**
+      * Add a binary attribute (e.g. CKA_ID / AttributeType::Id).
+      * @param attribute attribute type
+      * @param value binary attribute value to add
+      * @param length size of the binary attribute value in bytes
+      */
       void add_binary(AttributeType attribute, const byte* value, size_t length);
 
-      /// Add a binary attribute (e.g. CKA_ID / AttributeType::Id)
+      /**
+      * Add a binary attribute (e.g. CKA_ID / AttributeType::Id).
+      * @param attribute attribute type
+      * @param value binary attribute value to add
+      * @param length size of the binary attribute value in bytes
+      */
       template<typename TAlloc>
       void add_binary(AttributeType attribute, const std::vector<byte, TAlloc>& binary)
          {
          add_binary(attribute, binary.data(), binary.size());
          }
 
-      /// Add a bool attribute (e.g. CKA_SENSITIVE / AttributeType::Sensitive)
+      /**
+      * Add a bool attribute (e.g. CKA_SENSITIVE / AttributeType::Sensitive).
+      * @param attribute attribute type
+      * @param value boolean value to add
+      */
       void add_bool(AttributeType attribute, bool value);
 
-      /// Add a numeric attribute (e.g. CKA_MODULUS_BITS / AttributeType::ModulusBits)
+      /**
+      * Add a numeric attribute (e.g. CKA_MODULUS_BITS / AttributeType::ModulusBits).
+      * @param attribute attribute type
+      * @param value numeric value to add
+      */
       template<typename T>
       void add_numeric(AttributeType attribute, T value)
          {
@@ -92,7 +118,7 @@ class BOTAN_DLL AttributeContainer
          }
 
    protected:
-      /// Add a attribute with the given value and size to the attribute collection `m_attributes`
+      /// Add an attribute with the given value and size to the attribute collection `m_attributes`
       void add_attribute(AttributeType attribute, const byte* value, uint32_t size);
 
    private:
@@ -610,6 +636,9 @@ class BOTAN_DLL DomainParameterProperties : public StorageObjectProperties
       const KeyType m_key_type;
    };
 
+/**
+* Represents a PKCS#11 object.
+*/
 class BOTAN_DLL Object
    {
    public: