Doxygen comments

4 files changed, 183 insertions, 26 deletions

diff --git a/src/engine/engine.h b/src/engine/engine.h
index 9937d1dda..6e8133692 100644
--- a/src/engine/engine.h
+++ b/src/engine/engine.h
@@ -34,56 +34,124 @@ class BOTAN_DLL Engine
    public:
       virtual ~Engine() {}
 
+      /**
+      * @return name of this engine
+      */
       virtual std::string provider_name() const = 0;
 
-      // Lookup functions
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual BlockCipher*
-         find_block_cipher(const SCAN_Name&, Algorithm_Factory&) const
+         find_block_cipher(const SCAN_Name& algo_spec,
+                           Algorithm_Factory& af) const
          { return 0; }
 
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual StreamCipher*
-         find_stream_cipher(const SCAN_Name&, Algorithm_Factory&) const
+         find_stream_cipher(const SCAN_Name& algo_spec,
+                            Algorithm_Factory& af) const
          { return 0; }
 
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual HashFunction*
-         find_hash(const SCAN_Name&, Algorithm_Factory&) const
+         find_hash(const SCAN_Name& algo_spec,
+                   Algorithm_Factory& af) const
          { return 0; }
 
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual MessageAuthenticationCode*
-         find_mac(const SCAN_Name&, Algorithm_Factory&) const
+         find_mac(const SCAN_Name& algo_spec,
+                  Algorithm_Factory& af) const
          { return 0; }
 
+      /**
+      * @param n the modulus
+      * @param hints any use hints
+      * @return newly allocated object, or NULL
+      */
       virtual Modular_Exponentiator*
-         mod_exp(const BigInt&, Power_Mod::Usage_Hints) const
+         mod_exp(const BigInt& n,
+                 Power_Mod::Usage_Hints hints) const
          { return 0; }
 
-      virtual Keyed_Filter* get_cipher(const std::string&,
-                                       Cipher_Dir,
-                                       Algorithm_Factory&)
+      /**
+      * Return a new cipher object
+      * @param algo_spec the algorithm name/specification
+      * @param dir specifies if encryption or decryption is desired
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
+      virtual Keyed_Filter* get_cipher(const std::string& algo_spec,
+                                       Cipher_Dir dir,
+                                       Algorithm_Factory& af)
          { return 0; }
 
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
       virtual PK_Ops::Key_Agreement*
-         get_key_agreement_op(const Private_Key&) const
+         get_key_agreement_op(const Private_Key& key) const
          {
          return 0;
          }
 
-      virtual PK_Ops::Signature* get_signature_op(const Private_Key&) const
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Signature*
+         get_signature_op(const Private_Key& key) const
          {
          return 0;
          }
 
-      virtual PK_Ops::Verification* get_verify_op(const Public_Key&) const
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Verification*
+         get_verify_op(const Public_Key& key) const
          {
          return 0;
          }
 
-      virtual PK_Ops::Encryption* get_encryption_op(const Public_Key&) const
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Encryption*
+         get_encryption_op(const Public_Key& key) const
          {
          return 0;
          }
 
-      virtual PK_Ops::Decryption* get_decryption_op(const Private_Key&) const
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Decryption*
+         get_decryption_op(const Private_Key& key) const
          {
          return 0;
          }
diff --git a/src/filters/modes/eax/eax.h b/src/filters/modes/eax/eax.h
index 750f77aa3..7d45a18ba 100644
--- a/src/filters/modes/eax/eax.h
+++ b/src/filters/modes/eax/eax.h
@@ -21,16 +21,31 @@ namespace Botan {
 class BOTAN_DLL EAX_Base : public Keyed_Filter
    {
    public:
-      void set_key(const SymmetricKey&);
-      void set_iv(const InitializationVector&);
-      void set_header(const byte[], u32bit);
+      void set_key(const SymmetricKey& key);
+      void set_iv(const InitializationVector& iv);
+
+      /**
+      * Set some additional data that is not included in the
+      * ciphertext but that will be authenticated.
+      * @param header the header contents
+      * @param header_len length of header in bytes
+      */
+      void set_header(const byte header[], u32bit header_len);
+
+      /**
+      * @return name of this mode
+      */
       std::string name() const;
 
-      bool valid_keylength(u32bit) const;
+      bool valid_keylength(u32bit key_len) const;
 
       ~EAX_Base() { delete ctr; delete cmac; }
    protected:
-      EAX_Base(BlockCipher*, u32bit);
+      /**
+      * @param cipher the cipher to use
+      * @param tag_size is how big the auth tag will be
+      */
+      EAX_Base(BlockCipher* cipher, u32bit tag_size);
       void start_msg();
 
       const u32bit BLOCK_SIZE, TAG_SIZE;
@@ -49,9 +64,19 @@ class BOTAN_DLL EAX_Base : public Keyed_Filter
 class BOTAN_DLL EAX_Encryption : public EAX_Base
    {
    public:
+      /**
+      * @param ciph the cipher to use
+      * @param tag_size is how big the auth tag will be
+      */
       EAX_Encryption(BlockCipher* ciph, u32bit tag_size = 0) :
          EAX_Base(ciph, tag_size) {}
 
+      /**
+      * @param ciph the cipher to use
+      * @param key the key to use
+      * @param iv the initially set IV
+      * @param tag_size is how big the auth tag will be
+      */
       EAX_Encryption(BlockCipher* ciph, const SymmetricKey& key,
                      const InitializationVector& iv,
                      u32bit tag_size) : EAX_Base(ciph, tag_size)
@@ -70,8 +95,18 @@ class BOTAN_DLL EAX_Encryption : public EAX_Base
 class BOTAN_DLL EAX_Decryption : public EAX_Base
    {
    public:
+      /**
+      * @param ciph the cipher to use
+      * @param tag_size is how big the auth tag will be
+      */
       EAX_Decryption(BlockCipher* ciph, u32bit tag_size = 0);
 
+      /**
+      * @param ciph the cipher to use
+      * @param key the key to use
+      * @param iv the initially set IV
+      * @param tag_size is how big the auth tag will be
+      */
       EAX_Decryption(BlockCipher* ciph, const SymmetricKey& key,
                      const InitializationVector& iv,
                      u32bit tag_size = 0);
diff --git a/src/kdf/kdf.h b/src/kdf/kdf.h
index 614988f5a..ecf7f4621 100644
--- a/src/kdf/kdf.h
+++ b/src/kdf/kdf.h
@@ -19,25 +19,63 @@ namespace Botan {
 class BOTAN_DLL KDF
    {
    public:
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param salt a diversifier
+      */
       SecureVector<byte> derive_key(u32bit key_len,
                                     const MemoryRegion<byte>& secret,
                                     const std::string& salt = "") const;
 
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param salt a diversifier
+      */
       SecureVector<byte> derive_key(u32bit key_len,
                                     const MemoryRegion<byte>& secret,
                                     const MemoryRegion<byte>& salt) const;
 
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param salt a diversifier
+      * @param salt_len size of salt in bytes
+      */
       SecureVector<byte> derive_key(u32bit key_len,
                                     const MemoryRegion<byte>& secret,
-                                    const byte salt[], u32bit salt_len) const;
+                                    const byte salt[],
+                                    u32bit salt_len) const;
 
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param secret_len size of secret in bytes
+      * @param salt a diversifier
+      */
       SecureVector<byte> derive_key(u32bit key_len,
-                                    const byte secret[], u32bit secret_len,
+                                    const byte secret[],
+                                    u32bit secret_len,
                                     const std::string& salt = "") const;
 
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param secret_len size of secret in bytes
+      * @param salt a diversifier
+      * @param salt_len size of salt in bytes
+      */
       SecureVector<byte> derive_key(u32bit key_len,
-                                    const byte secret[], u32bit secret_len,
-                                    const byte salt[], u32bit salt_len) const;
+                                    const byte secret[],
+                                    u32bit secret_len,
+                                    const byte salt[],
+                                    u32bit salt_len) const;
 
       virtual ~KDF() {}
    private:
diff --git a/src/pubkey/pk_keys.h b/src/pubkey/pk_keys.h
index 781c8e70f..e90fcf51a 100644
--- a/src/pubkey/pk_keys.h
+++ b/src/pubkey/pk_keys.h
@@ -73,7 +73,11 @@ class BOTAN_DLL Public_Key
 
       virtual ~Public_Key() {}
    protected:
-      virtual void load_check(RandomNumberGenerator&) const;
+      /**
+      * Self-test after loading a key
+      * @param rng a random number generator
+      */
+      virtual void load_check(RandomNumberGenerator& rng) const;
    };
 
 /**
@@ -95,8 +99,17 @@ class BOTAN_DLL Private_Key : public virtual Public_Key
          { return algorithm_identifier(); }
 
    protected:
-      void load_check(RandomNumberGenerator&) const;
-      void gen_check(RandomNumberGenerator&) const;
+      /**
+      * Self-test after loading a key
+      * @param rng a random number generator
+      */
+      void load_check(RandomNumberGenerator& rng) const;
+
+      /**
+      * Self-test after generating a key
+      * @param rng a random number generator
+      */
+      void gen_check(RandomNumberGenerator& rng) const;
    };
 
 /**
@@ -105,6 +118,9 @@ class BOTAN_DLL Private_Key : public virtual Public_Key
 class BOTAN_DLL PK_Key_Agreement_Key : public virtual Private_Key
    {
    public:
+      /*
+      * @return public component of this key
+      */
       virtual MemoryVector<byte> public_value() const = 0;
 
       virtual ~PK_Key_Agreement_Key() {}