More Doxygen comments

24 files changed, 235 insertions, 28 deletions

diff --git a/src/algo_factory/algo_factory.h b/src/algo_factory/algo_factory.h
index 3284942ad..5e0e49f13 100644
--- a/src/algo_factory/algo_factory.h
+++ b/src/algo_factory/algo_factory.h
@@ -162,7 +162,14 @@ class BOTAN_DLL Algorithm_Factory
       class BOTAN_DLL Engine_Iterator
          {
          public:
+            /**
+            * @return next engine in the sequence
+            */
             class Engine* next() { return af.get_engine_n(n++); }
+
+            /**
+            * @param a an algorithm factory
+            */
             Engine_Iterator(const Algorithm_Factory& a) : af(a) { n = 0; }
          private:
             const Algorithm_Factory& af;
diff --git a/src/constructs/tss/tss.h b/src/constructs/tss/tss.h
index 440132eb9..485e42c53 100644
--- a/src/constructs/tss/tss.h
+++ b/src/constructs/tss/tss.h
@@ -22,12 +22,12 @@ class BOTAN_DLL RTSS_Share
    {
    public:
       /**
-      * @arg M the number of shares needed to reconstruct
-      * @arg N the number of shares generated
-      * @arg secret the secret to split
-      * @arg secret_len the length of the secret
-      * @arg identifier the 16 byte share identifier
-      * @arg rng the random number generator to use
+      * @param M the number of shares needed to reconstruct
+      * @param N the number of shares generated
+      * @param secret the secret to split
+      * @param secret_len the length of the secret
+      * @param identifier the 16 byte share identifier
+      * @param rng the random number generator to use
       */
       static std::vector<RTSS_Share>
          split(byte M, byte N,
@@ -36,18 +36,36 @@ class BOTAN_DLL RTSS_Share
                RandomNumberGenerator& rng);
 
       /**
-      * @arg shares the list of shares
+      * @param shares the list of shares
       */
       static SecureVector<byte>
         reconstruct(const std::vector<RTSS_Share>& shares);
 
       RTSS_Share() {}
-      RTSS_Share(const std::string&);
 
+      /**
+      * @param hex_input the share encoded in hexadecimal
+      */
+      RTSS_Share(const std::string& hex_input);
+
+      /**
+      * @return hex representation
+      */
       std::string to_string() const;
+
+      /**
+      * @return share identifier
+      */
       byte share_id() const;
 
+      /**
+      * @return size of this share in bytes
+      */
       u32bit size() const { return contents.size(); }
+
+      /**
+      * @return if this TSS share was initialized or not
+      */
       bool initialized() const { return (contents.size() > 0); }
    private:
       SecureVector<byte> contents;
diff --git a/src/hash/comb4p/comb4p.h b/src/hash/comb4p/comb4p.h
index 424512092..550b70b14 100644
--- a/src/hash/comb4p/comb4p.h
+++ b/src/hash/comb4p/comb4p.h
@@ -16,9 +16,13 @@ namespace Botan {
 * Combines two hash functions using a Feistel scheme. Described in
 * "On the Security of Hash Function Combiners", Anja Lehmann
 */
-class Comb4P : public HashFunction
+class BOTAN_DLL Comb4P : public HashFunction
    {
    public:
+      /**
+      * @param h1 the first hash
+      * @param h2 the second hash
+      */
       Comb4P(HashFunction* h1, HashFunction* h2);
 
       ~Comb4P() { delete hash1; delete hash2; }
diff --git a/src/hash/hash.h b/src/hash/hash.h
index 7cdfc6712..4f753f765 100644
--- a/src/hash/hash.h
+++ b/src/hash/hash.h
@@ -40,8 +40,13 @@ class BOTAN_DLL HashFunction : public BufferedComputation
       */
       virtual void clear() = 0;
 
+      /**
+      * @param hash_len the output length
+      * @param block_len the internal block size (if applicable)
+      */
       HashFunction(u32bit hash_len, u32bit block_len = 0) :
          BufferedComputation(hash_len), HASH_BLOCK_SIZE(block_len) {}
+
       virtual ~HashFunction() {}
    private:
       HashFunction& operator=(const HashFunction&);
diff --git a/src/hash/par_hash/par_hash.h b/src/hash/par_hash/par_hash.h
index 34d69e39a..d82a74a19 100644
--- a/src/hash/par_hash/par_hash.h
+++ b/src/hash/par_hash/par_hash.h
@@ -23,7 +23,10 @@ class BOTAN_DLL Parallel : public HashFunction
       std::string name() const;
       HashFunction* clone() const;
 
-      Parallel(const std::vector<HashFunction*>&);
+      /**
+      * @param hashes a set of hashes to compute in parallel
+      */
+      Parallel(const std::vector<HashFunction*>& hashes);
       ~Parallel();
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/hash/sha1/sha160.h b/src/hash/sha1/sha160.h
index 3d46e0c79..c66831a1e 100644
--- a/src/hash/sha1/sha160.h
+++ b/src/hash/sha1/sha160.h
@@ -24,6 +24,12 @@ class BOTAN_DLL SHA_160 : public MDx_HashFunction
       SHA_160();
 
    protected:
+      /**
+      * Set a custom size for the W array. Normally 80, but some
+      * subclasses need slightly more for best performance/internal
+      * constraints
+      * @param W_size how big to make W
+      */
       SHA_160(u32bit W_size);
 
       void compress_n(const byte[], u32bit blocks);
diff --git a/src/hash/sha2/sha2_32.h b/src/hash/sha2/sha2_32.h
index 319432122..e8e60d07c 100644
--- a/src/hash/sha2/sha2_32.h
+++ b/src/hash/sha2/sha2_32.h
@@ -20,6 +20,10 @@ class BOTAN_DLL SHA_224_256_BASE : public MDx_HashFunction
    {
    protected:
       void clear();
+
+      /**
+      * @param out output size in bytes
+      */
       SHA_224_256_BASE(u32bit out) :
          MDx_HashFunction(out, 64, true, true) { clear(); }
 
diff --git a/src/hash/sha2/sha2_64.h b/src/hash/sha2/sha2_64.h
index 5094fc0d2..bf87eb62d 100644
--- a/src/hash/sha2/sha2_64.h
+++ b/src/hash/sha2/sha2_64.h
@@ -20,6 +20,9 @@ class BOTAN_DLL SHA_384_512_BASE : public MDx_HashFunction
    protected:
       void clear();
 
+      /**
+      * @param out output size in bytes
+      */
       SHA_384_512_BASE(u32bit out) :
          MDx_HashFunction(out, 128, true, true, 16) {}
 
diff --git a/src/hash/skein/skein_512.h b/src/hash/skein/skein_512.h
index b2ec57962..5d17fa564 100644
--- a/src/hash/skein/skein_512.h
+++ b/src/hash/skein/skein_512.h
@@ -20,6 +20,11 @@ namespace Botan {
 class BOTAN_DLL Skein_512 : public HashFunction
    {
    public:
+      /**
+      * @param output_bits the output size of Skein in bits
+      * @param personalization is a string that will paramaterize the
+      * hash output
+      */
       Skein_512(u32bit output_bits = 512,
                 const std::string& personalization = "");
 
diff --git a/src/libstate/init.h b/src/libstate/init.h
index 4c4a09d1f..2d70e4370 100644
--- a/src/libstate/init.h
+++ b/src/libstate/init.h
@@ -22,8 +22,15 @@ namespace Botan {
 class BOTAN_DLL LibraryInitializer
    {
    public:
+      /**
+      * Initialize the library
+      * @param options a string listing initialization options
+      */
       static void initialize(const std::string& options = "");
 
+      /**
+      * Shutdown the library
+      */
       static void deinitialize();
 
       /**
diff --git a/src/libstate/libstate.h b/src/libstate/libstate.h
index 058b70e74..d7fb6e02c 100644
--- a/src/libstate/libstate.h
+++ b/src/libstate/libstate.h
@@ -29,6 +29,9 @@ class BOTAN_DLL Library_State
       Library_State();
       ~Library_State();
 
+      /**
+      * @param thread_safe should a mutex be used for serialization
+      */
       void initialize(bool thread_safe);
 
       /**
diff --git a/src/mac/cbc_mac/cbc_mac.h b/src/mac/cbc_mac/cbc_mac.h
index 3818cce84..772abd38f 100644
--- a/src/mac/cbc_mac/cbc_mac.h
+++ b/src/mac/cbc_mac/cbc_mac.h
@@ -23,7 +23,10 @@ class BOTAN_DLL CBC_MAC : public MessageAuthenticationCode
       std::string name() const;
       MessageAuthenticationCode* clone() const;
 
-      CBC_MAC(BlockCipher* e);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      CBC_MAC(BlockCipher* cipher);
       ~CBC_MAC();
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/mac/cmac/cmac.h b/src/mac/cmac/cmac.h
index bf7ccdc91..b5f3eec1a 100644
--- a/src/mac/cmac/cmac.h
+++ b/src/mac/cmac/cmac.h
@@ -23,10 +23,18 @@ class BOTAN_DLL CMAC : public MessageAuthenticationCode
       std::string name() const;
       MessageAuthenticationCode* clone() const;
 
+      /**
+      * CMAC's polynomial doubling operation
+      * @param in the input
+      * @param polynomial the byte value of the polynomial
+      */
       static SecureVector<byte> poly_double(const MemoryRegion<byte>& in,
                                             byte polynomial);
 
-      CMAC(BlockCipher* e);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      CMAC(BlockCipher* cipher);
       ~CMAC();
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/mac/mac.h b/src/mac/mac.h
index b93ae473d..52ff9c94c 100644
--- a/src/mac/mac.h
+++ b/src/mac/mac.h
@@ -45,6 +45,12 @@ class BOTAN_DLL MessageAuthenticationCode : public BufferedComputation,
       */
       virtual void clear() = 0;
 
+      /**
+      * @param mac_len the output length of this MAC
+      * @param key_min the minimum key size
+      * @param key_max the maximum key size
+      * @param key_mod the modulo restriction on the key size
+      */
       MessageAuthenticationCode(u32bit mac_len,
                                 u32bit key_min,
                                 u32bit key_max = 0,
diff --git a/src/mac/ssl3mac/ssl3_mac.h b/src/mac/ssl3mac/ssl3_mac.h
index 631b67c44..019163ec8 100644
--- a/src/mac/ssl3mac/ssl3_mac.h
+++ b/src/mac/ssl3mac/ssl3_mac.h
@@ -23,7 +23,10 @@ class BOTAN_DLL SSL3_MAC : public MessageAuthenticationCode
       std::string name() const;
       MessageAuthenticationCode* clone() const;
 
-      SSL3_MAC(HashFunction*);
+      /**
+      * @param hash the underlying hash to use
+      */
+      SSL3_MAC(HashFunction* hash);
       ~SSL3_MAC() { delete hash; }
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/mac/x919_mac/x919_mac.h b/src/mac/x919_mac/x919_mac.h
index abd149ecd..8432db7d1 100644
--- a/src/mac/x919_mac/x919_mac.h
+++ b/src/mac/x919_mac/x919_mac.h
@@ -23,7 +23,10 @@ class BOTAN_DLL ANSI_X919_MAC : public MessageAuthenticationCode
       std::string name() const;
       MessageAuthenticationCode* clone() const;
 
-      ANSI_X919_MAC(BlockCipher*);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      ANSI_X919_MAC(BlockCipher* cipher);
       ~ANSI_X919_MAC();
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/pbe/pbes1/pbes1.h b/src/pbe/pbes1/pbes1.h
index e0af8631b..d50c01f53 100644
--- a/src/pbe/pbes1/pbes1.h
+++ b/src/pbe/pbes1/pbes1.h
@@ -25,9 +25,14 @@ class BOTAN_DLL PBE_PKCS5v15 : public PBE
       void start_msg();
       void end_msg();
 
+      /**
+      * @param cipher the block cipher to use (DES or RC2)
+      * @param hash the hash function to use
+      * @param direction are we encrypting or decrypting
+      */
       PBE_PKCS5v15(BlockCipher* cipher,
                    HashFunction* hash,
-                   Cipher_Dir);
+                   Cipher_Dir direction);
 
       ~PBE_PKCS5v15();
    private:
diff --git a/src/s2k/pbkdf1/pbkdf1.h b/src/s2k/pbkdf1/pbkdf1.h
index cf439efd8..c0508d127 100644
--- a/src/s2k/pbkdf1/pbkdf1.h
+++ b/src/s2k/pbkdf1/pbkdf1.h
@@ -33,6 +33,10 @@ class BOTAN_DLL PKCS5_PBKDF1 : public S2K
       */
       PKCS5_PBKDF1(HashFunction* hash_in) : hash(hash_in) {}
 
+      /**
+      * Copy constructor
+      * @param other the object to copy
+      */
       PKCS5_PBKDF1(const PKCS5_PBKDF1& other) :
          S2K(), hash(other.hash->clone()) {}
 
diff --git a/src/s2k/pgps2k/pgp_s2k.h b/src/s2k/pgps2k/pgp_s2k.h
index d4c6a02bb..cfe9bf5d5 100644
--- a/src/s2k/pgps2k/pgp_s2k.h
+++ b/src/s2k/pgps2k/pgp_s2k.h
@@ -27,6 +27,9 @@ class BOTAN_DLL OpenPGP_S2K : public S2K
                              const byte salt[], u32bit salt_len,
                              u32bit iterations) const;
 
+      /**
+      * @param hash_in the hash function to use
+      */
       OpenPGP_S2K(HashFunction* hash_in) : hash(hash_in) {}
       ~OpenPGP_S2K() { delete hash; }
    private:
diff --git a/src/ssl/tls_alerts.h b/src/ssl/tls_alerts.h
index cb7529021..f189cf507 100644
--- a/src/ssl/tls_alerts.h
+++ b/src/ssl/tls_alerts.h
@@ -18,11 +18,19 @@ namespace Botan {
 class BOTAN_DLL Alert
    {
    public:
+      /**
+      * @return if this alert is a fatal one or not
+      */
       bool is_fatal() const { return fatal; }
+
+      /**
+      * @return type of alert
+      */
       Alert_Type type() const { return type_code; }
 
       /**
       * Deserialize an Alert message
+      * @param buf the serialized alert
       */
       Alert(const MemoryRegion<byte>& buf)
          {
diff --git a/src/stream/arc4/arc4.h b/src/stream/arc4/arc4.h
index 78c665985..0488783ef 100644
--- a/src/stream/arc4/arc4.h
+++ b/src/stream/arc4/arc4.h
@@ -26,7 +26,11 @@ class BOTAN_DLL ARC4 : public StreamCipher
 
       StreamCipher* clone() const { return new ARC4(SKIP); }
 
-      ARC4(u32bit = 0);
+      /**
+      * @param skip skip this many initial bytes in the keystream
+      */
+      ARC4(u32bit skip = 0);
+
       ~ARC4() { clear(); }
    private:
       void key_schedule(const byte[], u32bit);
diff --git a/src/stream/ctr/ctr.h b/src/stream/ctr/ctr.h
index 4e8d4de7f..fc7ba522f 100644
--- a/src/stream/ctr/ctr.h
+++ b/src/stream/ctr/ctr.h
@@ -33,7 +33,10 @@ class BOTAN_DLL CTR_BE : public StreamCipher
 
       void clear();
 
-      CTR_BE(BlockCipher*);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      CTR_BE(BlockCipher* cipher);
       ~CTR_BE();
    private:
       void key_schedule(const byte key[], u32bit key_len);
diff --git a/src/stream/ofb/ofb.h b/src/stream/ofb/ofb.h
index de212ec2c..2871dd8ee 100644
--- a/src/stream/ofb/ofb.h
+++ b/src/stream/ofb/ofb.h
@@ -33,7 +33,10 @@ class BOTAN_DLL OFB : public StreamCipher
 
       void clear();
 
-      OFB(BlockCipher*);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      OFB(BlockCipher* cipher);
       ~OFB();
    private:
       void key_schedule(const byte key[], u32bit key_len);
diff --git a/src/sym_algo/symkey.h b/src/sym_algo/symkey.h
index 0d12377bd..450dab306 100644
--- a/src/sym_algo/symkey.h
+++ b/src/sym_algo/symkey.h
@@ -19,37 +19,126 @@ namespace Botan {
 class BOTAN_DLL OctetString
    {
    public:
+      /**
+      * @return size of this octet string in bytes
+      */
       u32bit length() const { return bits.size(); }
+
+      /**
+      * @return this object as a SecureVector<byte>
+      */
       SecureVector<byte> bits_of() const { return bits; }
 
+      /**
+      * @return start of this string
+      */
       const byte* begin() const { return bits.begin(); }
+
+      /**
+      * @return end of this string
+      */
       const byte* end() const   { return bits.end(); }
 
+      /**
+      * @return this encoded as hex
+      */
       std::string as_string() const;
 
-      OctetString& operator^=(const OctetString&);
+      /**
+      * XOR the contents of another octet string into this one
+      * @param other octet string
+      * @return reference to this
+      */
+      OctetString& operator^=(const OctetString& other);
 
+      /**
+      * Force to have odd parity
+      */
       void set_odd_parity();
 
-      void change(const std::string&);
-      void change(const byte[], u32bit);
+      /**
+      * Change the contents of this octet string
+      * @param hex_string a hex encoded bytestring
+      */
+      void change(const std::string& hex_string);
+
+      /**
+      * Change the contents of this octet string
+      * @param in the input
+      * @param length of in in bytes
+      */
+      void change(const byte in[], u32bit length);
+
+      /**
+      * Change the contents of this octet string
+      * @param in the input
+      */
       void change(const MemoryRegion<byte>& in) { bits = in; }
 
-      OctetString(class RandomNumberGenerator&, u32bit len);
+      /**
+      * Create a new random OctetString
+      * @param rng is a random number generator
+      * @param len is the desired length in bytes
+      */
+      OctetString(class RandomNumberGenerator& rng, u32bit len);
+
+      /**
+      * Create a new OctetString
+      * @param str is a hex encoded string
+      */
       OctetString(const std::string& str = "") { change(str); }
+
+      /**
+      * Create a new OctetString
+      * @param in is an array
+      * @param len is the length of in in bytes
+      */
       OctetString(const byte in[], u32bit len) { change(in, len); }
+
+      /**
+      * Create a new OctetString
+      * @param in a bytestring
+      */
       OctetString(const MemoryRegion<byte>& in) { change(in); }
    private:
       SecureVector<byte> bits;
    };
 
-/*
-* Operations on Octet Strings
+/**
+* Compare two strings
+* @param x an octet string
+* @param y an octet string
+* @return if x is equal to y
+*/
+BOTAN_DLL bool operator==(const OctetString& x,
+                          const OctetString& y);
+
+/**
+* Compare two strings
+* @param x an octet string
+* @param y an octet string
+* @return if x is not equal to y
+*/
+BOTAN_DLL bool operator!=(const OctetString& x,
+                          const OctetString& y);
+
+/**
+* Concatenate two strings
+* @param x an octet string
+* @param y an octet string
+* @return x concatenated with y
+*/
+BOTAN_DLL OctetString operator+(const OctetString& x,
+                                const OctetString& y);
+
+/**
+* XOR two strings
+* @param x an octet string
+* @param y an octet string
+* @return x XORed with y
 */
-BOTAN_DLL bool operator==(const OctetString&, const OctetString&);
-BOTAN_DLL bool operator!=(const OctetString&, const OctetString&);
-BOTAN_DLL OctetString operator+(const OctetString&, const OctetString&);
-BOTAN_DLL OctetString operator^(const OctetString&, const OctetString&);
+BOTAN_DLL OctetString operator^(const OctetString& x,
+                                const OctetString& y);
 
 /*
 * Alternate Names