Yet more Doxygen comments

20 files changed, 217 insertions, 98 deletions

diff --git a/src/algo_factory/algo_cache.h b/src/algo_factory/algo_cache.h
index 13df8e752..ad8d41383 100644
--- a/src/algo_factory/algo_cache.h
+++ b/src/algo_factory/algo_cache.h
@@ -29,11 +29,19 @@ template<typename T>
 class Algorithm_Cache
    {
    public:
+      /**
+      * @param algo_spec names the requested algorithm
+      * @param pref_provider suggests a preferred provider
+      * @return a prototype object, or NULL
+      */
       const T* get(const std::string& algo_spec,
                    const std::string& pref_provider);
 
       /**
       * Add a new algorithm implementation to the cache
+      * @param algo the algorithm prototype object
+      * @param requested_name how this name will be requested
+      * @param provider_name is the name of the provider of this prototype
       */
       void add(T* algo,
                const std::string& requested_name,
@@ -41,12 +49,16 @@ class Algorithm_Cache
 
       /**
       * Set the preferred provider
+      * @param algo_spec names the algorithm
+      * @param provider names the preferred provider
       */
       void set_preferred_provider(const std::string& algo_spec,
                                   const std::string& provider);
 
       /**
       * Return the list of providers of this algorithm
+      * @param algo_name names the algorithm
+      * @return list of providers of this algorithm
       */
       std::vector<std::string> providers_of(const std::string& algo_name);
 
@@ -70,7 +82,7 @@ class Algorithm_Cache
       std::map<std::string, std::map<std::string, T*> > algorithms;
    };
 
-/**
+/*
 * Look for an algorithm implementation in the cache, also checking aliases
 * Assumes object lock is held
 */
@@ -93,7 +105,7 @@ Algorithm_Cache<T>::find_algorithm(const std::string& algo_spec)
    return algo;
    }
 
-/**
+/*
 * Look for an algorithm implementation by a particular provider
 */
 template<typename T>
@@ -141,7 +153,7 @@ const T* Algorithm_Cache<T>::get(const std::string& algo_spec,
    return prototype;
    }
 
-/**
+/*
 * Add an implementation to the cache
 */
 template<typename T>
@@ -164,7 +176,7 @@ void Algorithm_Cache<T>::add(T* algo,
       }
    }
 
-/**
+/*
 * Find the providers of this algo (if any)
 */
 template<typename T> std::vector<std::string>
@@ -190,7 +202,7 @@ Algorithm_Cache<T>::providers_of(const std::string& algo_name)
    return providers;
    }
 
-/**
+/*
 * Set the preferred provider for an algorithm
 */
 template<typename T>
@@ -202,7 +214,7 @@ void Algorithm_Cache<T>::set_preferred_provider(const std::string& algo_spec,
    pref_providers[algo_spec] = provider;
    }
 
-/**
+/*
 * Algorithm_Cache<T> Destructor
 */
 template<typename T>
diff --git a/src/block/aes/aes.cpp b/src/block/aes/aes.cpp
index 257dfd183..bf9a4198b 100644
--- a/src/block/aes/aes.cpp
+++ b/src/block/aes/aes.cpp
@@ -409,7 +409,7 @@ const u32bit TD[1024] = {
 
 }
 
-/**
+/*
 * AES Encryption
 */
 void AES::encrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -503,7 +503,7 @@ void AES::encrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES Decryption
 */
 void AES::decrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -583,7 +583,7 @@ void AES::decrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES Key Schedule
 */
 void AES::key_schedule(const byte key[], u32bit length)
@@ -636,7 +636,7 @@ void AES::key_schedule(const byte key[], u32bit length)
    DK.copy(XDK, length + 24);
    }
 
-/**
+/*
 * AES Byte Substitution
 */
 u32bit AES::S(u32bit input)
@@ -645,7 +645,7 @@ u32bit AES::S(u32bit input)
                       SE[get_byte(2, input)], SE[get_byte(3, input)]);
    }
 
-/**
+/*
 * AES Constructor
 */
 AES::AES(u32bit key_size) : BlockCipher(16, key_size)
@@ -655,7 +655,7 @@ AES::AES(u32bit key_size) : BlockCipher(16, key_size)
    ROUNDS = (key_size / 4) + 6;
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void AES::clear()
diff --git a/src/block/aes/aes.h b/src/block/aes/aes.h
index 00b3163b7..8770bdb35 100644
--- a/src/block/aes/aes.h
+++ b/src/block/aes/aes.h
@@ -26,7 +26,12 @@ class BOTAN_DLL AES : public BlockCipher
       BlockCipher* clone() const { return new AES; }
 
       AES() : BlockCipher(16, 16, 32, 8) { ROUNDS = 14; }
-      AES(u32bit);
+
+      /**
+      * AES fixed to a particular key_size (16, 24, or 32 bytes)
+      * @param key_size the chosen fixed key size
+      */
+      AES(u32bit key_size);
    private:
       void key_schedule(const byte[], u32bit);
       static u32bit S(u32bit);
diff --git a/src/block/aes_intel/aes_intel.cpp b/src/block/aes_intel/aes_intel.cpp
index 0da523156..211bb3b47 100644
--- a/src/block/aes_intel/aes_intel.cpp
+++ b/src/block/aes_intel/aes_intel.cpp
@@ -100,7 +100,7 @@ __m128i aes_256_key_expansion(__m128i key, __m128i key2)
       B3 = _mm_aesdeclast_si128(B3, K);         \
       } while(0)
 
-/**
+/*
 * AES-128 Encryption
 */
 void AES_128_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -176,7 +176,7 @@ void AES_128_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-128 Decryption
 */
 void AES_128_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -252,7 +252,7 @@ void AES_128_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-128 Key Schedule
 */
 void AES_128_Intel::key_schedule(const byte key[], u32bit)
@@ -301,7 +301,7 @@ void AES_128_Intel::key_schedule(const byte key[], u32bit)
    _mm_storeu_si128(DK_mm + 10, K0);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void AES_128_Intel::clear()
@@ -310,7 +310,7 @@ void AES_128_Intel::clear()
    DK.clear();
    }
 
-/**
+/*
 * AES-192 Encryption
 */
 void AES_192_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -392,7 +392,7 @@ void AES_192_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-192 Decryption
 */
 void AES_192_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -474,7 +474,7 @@ void AES_192_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-192 Key Schedule
 */
 void AES_192_Intel::key_schedule(const byte key[], u32bit)
@@ -517,7 +517,7 @@ void AES_192_Intel::key_schedule(const byte key[], u32bit)
    _mm_storeu_si128(DK_mm + 12, EK_mm[0]);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void AES_192_Intel::clear()
@@ -526,7 +526,7 @@ void AES_192_Intel::clear()
    DK.clear();
    }
 
-/**
+/*
 * AES-256 Encryption
 */
 void AES_256_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -614,7 +614,7 @@ void AES_256_Intel::encrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-256 Decryption
 */
 void AES_256_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
@@ -702,7 +702,7 @@ void AES_256_Intel::decrypt_n(const byte in[], byte out[], u32bit blocks) const
       }
    }
 
-/**
+/*
 * AES-256 Key Schedule
 */
 void AES_256_Intel::key_schedule(const byte key[], u32bit)
@@ -767,7 +767,7 @@ void AES_256_Intel::key_schedule(const byte key[], u32bit)
    _mm_storeu_si128(DK_mm + 14, K0);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void AES_256_Intel::clear()
diff --git a/src/block/noekeon/noekeon.h b/src/block/noekeon/noekeon.h
index f1175f529..018c1d1fd 100644
--- a/src/block/noekeon/noekeon.h
+++ b/src/block/noekeon/noekeon.h
@@ -29,6 +29,10 @@ class BOTAN_DLL Noekeon : public BlockCipher
    private:
       void key_schedule(const byte[], u32bit);
    protected: // for access by SIMD subclass
+
+      /**
+      * The Noekeon round constants
+      */
       static const byte RC[17];
 
       SecureVector<u32bit, 4> EK, DK;
diff --git a/src/build-data/cc/gcc.txt b/src/build-data/cc/gcc.txt
index 6c5e4267f..6d68dc890 100644
--- a/src/build-data/cc/gcc.txt
+++ b/src/build-data/cc/gcc.txt
@@ -12,7 +12,7 @@ add_lib_option -l
 
 lang_flags "-D_REENTRANT -ansi -Wno-long-long"
 #warning_flags "-W -Wall"
-warning_flags "-Werror -Wextra -Wall -Wstrict-aliasing -Wstrict-overflow=5 -Wcast-align -Wmissing-declarations -Wno-unused-parameter -Wpointer-arith -Wcast-qual"
+warning_flags "-Werror -Wextra -Wall -Wstrict-aliasing -Wstrict-overflow=5 -Wcast-align -Wmissing-declarations -Wpointer-arith -Wcast-qual"
 
 lib_opt_flags "-O3"
 check_opt_flags "-O2"
diff --git a/src/entropy/entropy_src.h b/src/entropy/entropy_src.h
index 63fd6a1f7..898d650ce 100644
--- a/src/entropy/entropy_src.h
+++ b/src/entropy/entropy_src.h
@@ -20,23 +20,40 @@ namespace Botan {
 class BOTAN_DLL Entropy_Accumulator
    {
    public:
+      /**
+      * Initialize an Entropy_Accumulator
+      * @param goal is how many bits we would like to collect
+      */
       Entropy_Accumulator(u32bit goal) :
          entropy_goal(goal), collected_bits(0) {}
 
       virtual ~Entropy_Accumulator() {}
 
       /**
-      @return cached I/O buffer for repeated polls
+      * Get a cached I/O buffer (purely for minimizing allocation
+      * overhead to polls)
+      *
+      * @param size requested size for the I/O buffer
+      * @return cached I/O buffer for repeated polls
       */
       MemoryRegion<byte>& get_io_buffer(u32bit size)
          { io_buffer.resize(size); return io_buffer; }
 
+      /**
+      * @return number of bits collected so far
+      */
       u32bit bits_collected() const
          { return static_cast<u32bit>(collected_bits); }
 
+      /**
+      * @return if our polling goal has been achieved
+      */
       bool polling_goal_achieved() const
          { return (collected_bits >= entropy_goal); }
 
+      /**
+      * @return how many bits we need to reach our polling goal
+      */
       u32bit desired_remaining_bits() const
          {
          if(collected_bits >= entropy_goal)
@@ -44,12 +61,25 @@ class BOTAN_DLL Entropy_Accumulator
          return static_cast<u32bit>(entropy_goal - collected_bits);
          }
 
+      /**
+      * Add entropy to the accumulator
+      * @param bytes the input bytes
+      * @param length specifies how many bytes the input is
+      * @param entropy_bits_per_byte is a best guess at how much
+      * entropy per byte is in this input
+      */
       void add(const void* bytes, u32bit length, double entropy_bits_per_byte)
          {
          add_bytes(reinterpret_cast<const byte*>(bytes), length);
          collected_bits += entropy_bits_per_byte * length;
          }
 
+      /**
+      * Add entropy to the accumulator
+      * @param v is some value
+      * @param entropy_bits_per_byte is a best guess at how much
+      * entropy per byte is in this input
+      */
       template<typename T>
       void add(const T& v, double entropy_bits_per_byte)
          {
@@ -88,8 +118,17 @@ class BOTAN_DLL Entropy_Accumulator_BufferedComputation : public Entropy_Accumul
 class BOTAN_DLL EntropySource
    {
    public:
+      /**
+      * @return name identifying this entropy source
+      */
       virtual std::string name() const = 0;
+
+      /**
+      * Perform an entropy gathering poll
+      * @param accum is an accumulator object that will be given entropy
+      */
       virtual void poll(Entropy_Accumulator& accum) = 0;
+
       virtual ~EntropySource() {}
    };
 
diff --git a/src/hash/mdx_hash/mdx_hash.cpp b/src/hash/mdx_hash/mdx_hash.cpp
index 8326f7d4b..bf571076e 100644
--- a/src/hash/mdx_hash/mdx_hash.cpp
+++ b/src/hash/mdx_hash/mdx_hash.cpp
@@ -11,7 +11,7 @@
 
 namespace Botan {
 
-/**
+/*
 * MDx_HashFunction Constructor
 */
 MDx_HashFunction::MDx_HashFunction(u32bit hash_len, u32bit block_len,
@@ -25,7 +25,7 @@ MDx_HashFunction::MDx_HashFunction(u32bit hash_len, u32bit block_len,
    count = position = 0;
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void MDx_HashFunction::clear()
@@ -34,7 +34,7 @@ void MDx_HashFunction::clear()
    count = position = 0;
    }
 
-/**
+/*
 * Update the hash
 */
 void MDx_HashFunction::add_data(const byte input[], u32bit length)
@@ -64,7 +64,7 @@ void MDx_HashFunction::add_data(const byte input[], u32bit length)
    position += remaining;
    }
 
-/**
+/*
 * Finalize a hash
 */
 void MDx_HashFunction::final_result(byte output[])
@@ -86,7 +86,7 @@ void MDx_HashFunction::final_result(byte output[])
    clear();
    }
 
-/**
+/*
 * Write the count bits to the buffer
 */
 void MDx_HashFunction::write_count(byte out[])
diff --git a/src/hash/mdx_hash/mdx_hash.h b/src/hash/mdx_hash/mdx_hash.h
index dbd1435ba..087c7fc46 100644
--- a/src/hash/mdx_hash/mdx_hash.h
+++ b/src/hash/mdx_hash/mdx_hash.h
@@ -18,7 +18,19 @@ namespace Botan {
 class BOTAN_DLL MDx_HashFunction : public HashFunction
    {
    public:
-      MDx_HashFunction(u32bit, u32bit, bool, bool, u32bit = 8);
+      /**
+      * @param hash_length is the output length of this hash
+      * @param block_length is the number of bytes per block
+      * @param big_byte_endian specifies if the hash uses big-endian bytes
+      * @param big_bit_endian specifies if the hash uses big-endian bits
+      * @param counter_size specifies the size of the counter var in bytes
+      */
+      MDx_HashFunction(u32bit hash_length,
+                       u32bit block_length,
+                       bool big_byte_endian,
+                       bool big_bit_endian,
+                       u32bit counter_size = 8);
+
       virtual ~MDx_HashFunction() {}
    protected:
       void add_data(const byte input[], u32bit length);
diff --git a/src/libstate/scan_name.h b/src/libstate/scan_name.h
index 66eda688c..49c3d3765 100644
--- a/src/libstate/scan_name.h
+++ b/src/libstate/scan_name.h
@@ -23,64 +23,66 @@ class BOTAN_DLL SCAN_Name
    {
    public:
       /**
-      @param algo_spec A SCAN-format name
+      * @param algo_spec A SCAN-format name
       */
       SCAN_Name(std::string algo_spec);
 
       /**
-      @return the original input string
+      * @return the original input string
       */
       std::string as_string() const { return orig_algo_spec; }
 
       /**
-      @return the algorithm name
+      * @return the algorithm name
       */
       std::string algo_name() const { return alg_name; }
 
       /**
-      @return the algorithm name plus any arguments
+      * @return the algorithm name plus any arguments
       */
       std::string algo_name_and_args() const;
 
       /**
-      @return the number of arguments
+      * @return the number of arguments
       */
       u32bit arg_count() const { return args.size(); }
 
       /**
-      @return if the number of arguments is between lower and upper
+      * @param lower is the lower bound
+      * @param upper is the upper bound
+      * @return if the number of arguments is between lower and upper
       */
       bool arg_count_between(u32bit lower, u32bit upper) const
          { return ((arg_count() >= lower) && (arg_count() <= upper)); }
 
       /**
-      @param i which argument
-      @return the ith argument
+      * @param i which argument
+      * @return the ith argument
       */
       std::string arg(u32bit i) const;
 
       /**
-      @param i which argument
-      @param def_value the default value
-      @return the ith argument or the default value
+      * @param i which argument
+      * @param def_value the default value
+      * @return the ith argument or the default value
       */
       std::string arg(u32bit i, const std::string& def_value) const;
 
       /**
-      @param i which argument
-      @param def_value the default value
-      @return the ith argument as a u32bit, or the default value
+      * @param i which argument
+      * @param def_value the default value
+      * @return the ith argument as a u32bit, or the default value
       */
       u32bit arg_as_u32bit(u32bit i, u32bit def_value) const;
 
       /**
-      @return the cipher mode (if any)
+      * @return the cipher mode (if any)
       */
       std::string cipher_mode() const
          { return (mode_info.size() >= 1) ? mode_info[0] : ""; }
 
       /**
-      @return the cipher mode padding (if any)
+      * @return the cipher mode padding (if any)
       */
       std::string cipher_mode_pad() const
          { return (mode_info.size() >= 2) ? mode_info[1] : ""; }
diff --git a/src/pbe/pbes2/pbes2.cpp b/src/pbe/pbes2/pbes2.cpp
index 4a28193e1..1ac16af8d 100644
--- a/src/pbe/pbes2/pbes2.cpp
+++ b/src/pbe/pbes2/pbes2.cpp
@@ -21,7 +21,7 @@
 
 namespace Botan {
 
-/**
+/*
 * Encrypt some bytes using PBES2
 */
 void PBE_PKCS5v20::write(const byte input[], u32bit length)
@@ -35,7 +35,7 @@ void PBE_PKCS5v20::write(const byte input[], u32bit length)
       }
    }
 
-/**
+/*
 * Start encrypting with PBES2
 */
 void PBE_PKCS5v20::start_msg()
@@ -54,7 +54,7 @@ void PBE_PKCS5v20::start_msg()
       pipe.set_default_msg(pipe.default_msg() + 1);
    }
 
-/**
+/*
 * Finish encrypting with PBES2
 */
 void PBE_PKCS5v20::end_msg()
@@ -64,7 +64,7 @@ void PBE_PKCS5v20::end_msg()
    pipe.reset();
    }
 
-/**
+/*
 * Flush the pipe
 */
 void PBE_PKCS5v20::flush_pipe(bool safe_to_skip)
@@ -80,7 +80,7 @@ void PBE_PKCS5v20::flush_pipe(bool safe_to_skip)
       }
    }
 
-/**
+/*
 * Set the passphrase to use
 */
 void PBE_PKCS5v20::set_key(const std::string& passphrase)
@@ -92,7 +92,7 @@ void PBE_PKCS5v20::set_key(const std::string& passphrase)
                           iterations).bits_of();
    }
 
-/**
+/*
 * Create a new set of PBES2 parameters
 */
 void PBE_PKCS5v20::new_params(RandomNumberGenerator& rng)
@@ -107,7 +107,7 @@ void PBE_PKCS5v20::new_params(RandomNumberGenerator& rng)
    rng.randomize(iv, iv.size());
    }
 
-/**
+/*
 * Encode PKCS#5 PBES2 parameters
 */
 MemoryVector<byte> PBE_PKCS5v20::encode_params() const
@@ -136,7 +136,7 @@ MemoryVector<byte> PBE_PKCS5v20::encode_params() const
       .get_contents();
    }
 
-/**
+/*
 * Decode PKCS#5 PBES2 parameters
 */
 void PBE_PKCS5v20::decode_params(DataSource& source)
@@ -187,7 +187,7 @@ void PBE_PKCS5v20::decode_params(DataSource& source)
       throw Decoding_Error("PBE-PKCS5 v2.0: Encoded salt is too small");
    }
 
-/**
+/*
 * Return an OID for PBES2
 */
 OID PBE_PKCS5v20::get_oid() const
@@ -195,7 +195,7 @@ OID PBE_PKCS5v20::get_oid() const
    return OIDS::lookup("PBE-PKCS5v20");
    }
 
-/**
+/*
 * Check if this is a known PBES2 cipher
 */
 bool PBE_PKCS5v20::known_cipher(const std::string& algo)
@@ -207,7 +207,7 @@ bool PBE_PKCS5v20::known_cipher(const std::string& algo)
    return false;
    }
 
-/**
+/*
 * PKCS#5 v2.0 PBE Constructor
 */
 PBE_PKCS5v20::PBE_PKCS5v20(BlockCipher* cipher,
@@ -220,7 +220,7 @@ PBE_PKCS5v20::PBE_PKCS5v20(BlockCipher* cipher,
       throw Invalid_Argument("PBE-PKCS5 v2.0: Invalid digest " + digest->name());
    }
 
-/**
+/*
 * PKCS#5 v2.0 PBE Constructor
 */
 PBE_PKCS5v20::PBE_PKCS5v20(DataSource& params) : direction(DECRYPTION)
diff --git a/src/pbe/pbes2/pbes2.h b/src/pbe/pbes2/pbes2.h
index e5182af78..f24d572d0 100644
--- a/src/pbe/pbes2/pbes2.h
+++ b/src/pbe/pbes2/pbes2.h
@@ -21,14 +21,27 @@ namespace Botan {
 class BOTAN_DLL PBE_PKCS5v20 : public PBE
    {
    public:
-      static bool known_cipher(const std::string&);
+      /**
+      * @param cipher names a block cipher
+      * @return true iff PKCS #5 knows how to use this cipher
+      */
+      static bool known_cipher(const std::string& cipher);
 
       void write(const byte[], u32bit);
       void start_msg();
       void end_msg();
 
-      PBE_PKCS5v20(DataSource&);
-      PBE_PKCS5v20(BlockCipher*, HashFunction*);
+      /**
+      * Load a PKCS #5 v2.0 encrypted stream
+      * @param input is the input source
+      */
+      PBE_PKCS5v20(DataSource& input);
+
+      /**
+      * @param cipher the block cipher to use
+      * @param hash the hash function to use
+      */
+      PBE_PKCS5v20(BlockCipher* cipher, HashFunction* hash);
 
       ~PBE_PKCS5v20();
    private:
diff --git a/src/rng/hmac_rng/hmac_rng.cpp b/src/rng/hmac_rng/hmac_rng.cpp
index 3ce97ea46..fbfa87f70 100644
--- a/src/rng/hmac_rng/hmac_rng.cpp
+++ b/src/rng/hmac_rng/hmac_rng.cpp
@@ -31,7 +31,7 @@ void hmac_prf(MessageAuthenticationCode* prf,
 
 }
 
-/**
+/*
 * Generate a buffer of random bytes
 */
 void HMAC_RNG::randomize(byte out[], u32bit length)
@@ -54,7 +54,7 @@ void HMAC_RNG::randomize(byte out[], u32bit length)
       }
    }
 
-/**
+/*
 * Poll for entropy and reset the internal keys
 */
 void HMAC_RNG::reseed(u32bit poll_bits)
@@ -115,7 +115,7 @@ void HMAC_RNG::reseed(u32bit poll_bits)
       seeded = true;
    }
 
-/**
+/*
 * Add user-supplied entropy to the extractor input
 */
 void HMAC_RNG::add_entropy(const byte input[], u32bit length)
@@ -132,7 +132,7 @@ void HMAC_RNG::add_entropy(const byte input[], u32bit length)
       reseed(128);
    }
 
-/**
+/*
 * Add another entropy source to the list
 */
 void HMAC_RNG::add_entropy_source(EntropySource* src)
@@ -140,7 +140,7 @@ void HMAC_RNG::add_entropy_source(EntropySource* src)
    entropy_sources.push_back(src);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void HMAC_RNG::clear()
@@ -153,7 +153,7 @@ void HMAC_RNG::clear()
    seeded = false;
    }
 
-/**
+/*
 * Return the name of this type
 */
 std::string HMAC_RNG::name() const
@@ -161,7 +161,7 @@ std::string HMAC_RNG::name() const
    return "HMAC_RNG(" + extractor->name() + "," + prf->name() + ")";
    }
 
-/**
+/*
 * HMAC_RNG Constructor
 */
 HMAC_RNG::HMAC_RNG(MessageAuthenticationCode* extractor_mac,
@@ -209,7 +209,7 @@ HMAC_RNG::HMAC_RNG(MessageAuthenticationCode* extractor_mac,
    extractor->set_key(prf->process("Botan HMAC_RNG XTS"));
    }
 
-/**
+/*
 * HMAC_RNG Destructor
 */
 HMAC_RNG::~HMAC_RNG()
diff --git a/src/rng/hmac_rng/hmac_rng.h b/src/rng/hmac_rng/hmac_rng.h
index 452357130..fc712b3ec 100644
--- a/src/rng/hmac_rng/hmac_rng.h
+++ b/src/rng/hmac_rng/hmac_rng.h
@@ -36,6 +36,10 @@ class BOTAN_DLL HMAC_RNG : public RandomNumberGenerator
       void add_entropy_source(EntropySource* es);
       void add_entropy(const byte[], u32bit);
 
+      /**
+      * @param extractor a MAC used for extracting the entropy
+      * @param prf a MAC used as a PRF using HKDF construction
+      */
       HMAC_RNG(MessageAuthenticationCode* extractor,
                MessageAuthenticationCode* prf);
 
diff --git a/src/rng/randpool/randpool.cpp b/src/rng/randpool/randpool.cpp
index 9a4d77e55..c3e496638 100644
--- a/src/rng/randpool/randpool.cpp
+++ b/src/rng/randpool/randpool.cpp
@@ -15,7 +15,7 @@ namespace Botan {
 
 namespace {
 
-/**
+/*
 * PRF based on a MAC
 */
 enum RANDPOOL_PRF_TAG {
@@ -26,7 +26,7 @@ enum RANDPOOL_PRF_TAG {
 
 }
 
-/**
+/*
 * Generate a buffer of random bytes
 */
 void Randpool::randomize(byte out[], u32bit length)
@@ -45,7 +45,7 @@ void Randpool::randomize(byte out[], u32bit length)
       }
    }
 
-/**
+/*
 * Refill the output buffer
 */
 void Randpool::update_buffer()
@@ -66,7 +66,7 @@ void Randpool::update_buffer()
       mix_pool();
    }
 
-/**
+/*
 * Mix the entropy pool
 */
 void Randpool::mix_pool()
@@ -94,7 +94,7 @@ void Randpool::mix_pool()
    update_buffer();
    }
 
-/**
+/*
 * Reseed the internal state
 */
 void Randpool::reseed(u32bit poll_bits)
@@ -121,7 +121,7 @@ void Randpool::reseed(u32bit poll_bits)
       seeded = true;
    }
 
-/**
+/*
 * Add user-supplied entropy
 */
 void Randpool::add_entropy(const byte input[], u32bit length)
@@ -134,7 +134,7 @@ void Randpool::add_entropy(const byte input[], u32bit length)
       seeded = true;
    }
 
-/**
+/*
 * Add another entropy source to the list
 */
 void Randpool::add_entropy_source(EntropySource* src)
@@ -142,7 +142,7 @@ void Randpool::add_entropy_source(EntropySource* src)
    entropy_sources.push_back(src);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void Randpool::clear()
@@ -155,7 +155,7 @@ void Randpool::clear()
    seeded = false;
    }
 
-/**
+/*
 * Return the name of this type
 */
 std::string Randpool::name() const
@@ -163,7 +163,7 @@ std::string Randpool::name() const
    return "Randpool(" + cipher->name() + "," + mac->name() + ")";
    }
 
-/**
+/*
 * Randpool Constructor
 */
 Randpool::Randpool(BlockCipher* cipher_in,
@@ -194,7 +194,7 @@ Randpool::Randpool(BlockCipher* cipher_in,
    seeded = false;
    }
 
-/**
+/*
 * Randpool Destructor
 */
 Randpool::~Randpool()
diff --git a/src/rng/randpool/randpool.h b/src/rng/randpool/randpool.h
index ab6ed6748..471bb791a 100644
--- a/src/rng/randpool/randpool.h
+++ b/src/rng/randpool/randpool.h
@@ -30,7 +30,15 @@ class BOTAN_DLL Randpool : public RandomNumberGenerator
       void add_entropy_source(EntropySource* es);
       void add_entropy(const byte input[], u32bit length);
 
-      Randpool(BlockCipher* cipher, MessageAuthenticationCode* mac,
+      /**
+      * @param cipher a block cipher to use
+      * @param mac a message authentication code to use
+      * @param pool_blocks how many cipher blocks to use for the pool
+      * @param iterations_before_reseed how many times we'll use the
+      * internal state to generate output before reseeding
+      */
+      Randpool(BlockCipher* cipher,
+               MessageAuthenticationCode* mac,
                u32bit pool_blocks = 32,
                u32bit iterations_before_reseed = 128);
 
diff --git a/src/rng/x931_rng/x931_rng.cpp b/src/rng/x931_rng/x931_rng.cpp
index 3ff180898..f812377ed 100644
--- a/src/rng/x931_rng/x931_rng.cpp
+++ b/src/rng/x931_rng/x931_rng.cpp
@@ -11,7 +11,7 @@
 
 namespace Botan {
 
-/**
+/*
 * Generate a buffer of random bytes
 */
 void ANSI_X931_RNG::randomize(byte out[], u32bit length)
@@ -33,7 +33,7 @@ void ANSI_X931_RNG::randomize(byte out[], u32bit length)
       }
    }
 
-/**
+/*
 * Refill the internal state
 */
 void ANSI_X931_RNG::update_buffer()
@@ -52,7 +52,7 @@ void ANSI_X931_RNG::update_buffer()
    position = 0;
    }
 
-/**
+/*
 * Reset V and the cipher key with new values
 */
 void ANSI_X931_RNG::rekey()
@@ -71,7 +71,7 @@ void ANSI_X931_RNG::rekey()
       }
    }
 
-/**
+/*
 * Reseed the internal state
 */
 void ANSI_X931_RNG::reseed(u32bit poll_bits)
@@ -80,7 +80,7 @@ void ANSI_X931_RNG::reseed(u32bit poll_bits)
    rekey();
    }
 
-/**
+/*
 * Add a entropy source to the underlying PRNG
 */
 void ANSI_X931_RNG::add_entropy_source(EntropySource* src)
@@ -88,7 +88,7 @@ void ANSI_X931_RNG::add_entropy_source(EntropySource* src)
    prng->add_entropy_source(src);
    }
 
-/**
+/*
 * Add some entropy to the underlying PRNG
 */
 void ANSI_X931_RNG::add_entropy(const byte input[], u32bit length)
@@ -97,7 +97,7 @@ void ANSI_X931_RNG::add_entropy(const byte input[], u32bit length)
    rekey();
    }
 
-/**
+/*
 * Check if the the PRNG is seeded
 */
 bool ANSI_X931_RNG::is_seeded() const
@@ -105,7 +105,7 @@ bool ANSI_X931_RNG::is_seeded() const
    return (V.size() > 0);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void ANSI_X931_RNG::clear()
@@ -118,7 +118,7 @@ void ANSI_X931_RNG::clear()
    position = 0;
    }
 
-/**
+/*
 * Return the name of this type
 */
 std::string ANSI_X931_RNG::name() const
@@ -126,7 +126,7 @@ std::string ANSI_X931_RNG::name() const
    return "X9.31(" + cipher->name() + ")";
    }
 
-/**
+/*
 * ANSI X931 RNG Constructor
 */
 ANSI_X931_RNG::ANSI_X931_RNG(BlockCipher* cipher_in,
@@ -142,7 +142,7 @@ ANSI_X931_RNG::ANSI_X931_RNG(BlockCipher* cipher_in,
    position = 0;
    }
 
-/**
+/*
 * ANSI X931 RNG Destructor
 */
 ANSI_X931_RNG::~ANSI_X931_RNG()
diff --git a/src/rng/x931_rng/x931_rng.h b/src/rng/x931_rng/x931_rng.h
index d5ba2e9eb..345ee3ca9 100644
--- a/src/rng/x931_rng/x931_rng.h
+++ b/src/rng/x931_rng/x931_rng.h
@@ -28,7 +28,13 @@ class BOTAN_DLL ANSI_X931_RNG : public RandomNumberGenerator
       void add_entropy_source(EntropySource*);
       void add_entropy(const byte[], u32bit);
 
-      ANSI_X931_RNG(BlockCipher*, RandomNumberGenerator*);
+      /**
+      * @param cipher the block cipher to use in this PRNG
+      * @param rng the underlying PRNG for generating inputs
+      * (eg, an HMAC_RNG)
+      */
+      ANSI_X931_RNG(BlockCipher* cipher,
+                    RandomNumberGenerator* rng);
       ~ANSI_X931_RNG();
    private:
       void rekey();
diff --git a/src/stream/stream_cipher.h b/src/stream/stream_cipher.h
index 580fa85e2..edeb1aff5 100644
--- a/src/stream/stream_cipher.h
+++ b/src/stream/stream_cipher.h
@@ -59,6 +59,9 @@ class BOTAN_DLL StreamCipher : public SymmetricAlgorithm
 
       /**
       * StreamCipher constructor
+      * @param key_min the minimum key size
+      * @param key_max the maximum key size
+      * @param key_mod the modulo restriction on the key size
       */
       StreamCipher(u32bit key_min,
                    u32bit key_max = 0,
diff --git a/src/utils/buf_comp/buf_comp.h b/src/utils/buf_comp/buf_comp.h
index bbaa72919..2cc2d87a9 100644
--- a/src/utils/buf_comp/buf_comp.h
+++ b/src/utils/buf_comp/buf_comp.h
@@ -117,8 +117,19 @@ class BOTAN_DLL BufferedComputation
       virtual ~BufferedComputation() {}
    private:
       BufferedComputation& operator=(const BufferedComputation&);
-      virtual void add_data(const byte[], u32bit) = 0;
-      virtual void final_result(byte[]) = 0;
+
+      /**
+      * Add more data to the computation
+      * @param input is an input buffer
+      * @param length is the length of input in bytes
+      */
+      virtual void add_data(const byte input[], u32bit length) = 0;
+
+      /**
+      * Write the final output to out
+      * @param out is an output buffer of OUTPUT_LENGTH
+      */
+      virtual void final_result(byte out[]) = 0;
    };
 
 }