merge of '3632315d498b1223cca850051518f7a3273f5449'

     and '5c9cdb3b727e7336f0a18f72e6ca2eb7460d31ec'

63 files changed, 581 insertions, 336 deletions

diff --git a/src/algo_factory/algo_cache.h b/src/algo_factory/algo_cache.h
index 13df8e752..376af130b 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 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/alloc/secmem.h b/src/alloc/secmem.h
index d1a3ba7bd..39b5549a9 100644
--- a/src/alloc/secmem.h
+++ b/src/alloc/secmem.h
@@ -24,7 +24,7 @@ class MemoryRegion
       /**
       * Find out the size of the buffer, i.e. how many objects of type T it
       * contains.
-      * @return the size of the buffer
+      * @return size of the buffer
       */
       u32bit size() const { return used; }
 
@@ -36,37 +36,37 @@ class MemoryRegion
 
       /**
       * Get a pointer to the first element in the buffer.
-      * @return a pointer to the first element in the buffer
+      * @return pointer to the first element in the buffer
       */
       operator T* () { return buf; }
 
       /**
       * Get a constant pointer to the first element in the buffer.
-      * @return a constant pointer to the first element in the buffer
+      * @return constant pointer to the first element in the buffer
       */
       operator const T* () const { return buf; }
 
       /**
       * Get a pointer to the first element in the buffer.
-      * @return a pointer to the first element in the buffer
+      * @return pointer to the first element in the buffer
       */
       T* begin() { return buf; }
 
       /**
       * Get a constant pointer to the first element in the buffer.
-      * @return a constant pointer to the first element in the buffer
+      * @return constant pointer to the first element in the buffer
       */
       const T* begin() const { return buf; }
 
       /**
       * Get a pointer to the last element in the buffer.
-      * @return a pointer to the last element in the buffer
+      * @return pointer to the last element in the buffer
       */
       T* end() { return (buf + size()); }
 
       /**
       * Get a constant pointer to the last element in the buffer.
-      * @return a constant pointer to the last element in the buffer
+      * @return constant pointer to the last element in the buffer
       */
       const T* end() const { return (buf + size()); }
 
@@ -98,7 +98,7 @@ class MemoryRegion
       * Copy the contents of another buffer into this buffer.
       * The former contents of *this are discarded.
       * @param other the buffer to copy the contents from.
-      * @return a reference to *this
+      * @return reference to *this
       */
       MemoryRegion<T>& operator=(const MemoryRegion<T>& other)
          { if(this != &other) set(other); return (*this); }
@@ -299,7 +299,7 @@ class MemoryVector : public MemoryRegion<T>
       /**
       * Copy the contents of another buffer into this buffer.
       * @param in the buffer to copy the contents from
-      * @return a reference to *this
+      * @return reference to *this
       */
       MemoryVector<T>& operator=(const MemoryRegion<T>& in)
          { if(this != &in) set(in); return (*this); }
@@ -352,7 +352,7 @@ class SecureVector : public MemoryRegion<T>
       /**
       * Copy the contents of another buffer into this buffer.
       * @param in the buffer to copy the contents from
-      * @return a reference to *this
+      * @return reference to *this
       */
       SecureVector<T>& operator=(const MemoryRegion<T>& in)
          { if(this != &in) set(in); return (*this); }
diff --git a/src/asn1/asn1_oid.h b/src/asn1/asn1_oid.h
index e6d077bee..b3db97744 100644
--- a/src/asn1/asn1_oid.h
+++ b/src/asn1/asn1_oid.h
@@ -31,13 +31,13 @@ class BOTAN_DLL OID : public ASN1_Object
 
       /**
       * Get this OID as list (vector) of its components.
-      * @return a vector representing this OID
+      * @return vector representing this OID
       */
       std::vector<u32bit> get_id() const { return id; }
 
       /**
       * Get this OID as a string
-      * @return a string representing this OID
+      * @return string representing this OID
       */
       std::string as_string() const;
 
@@ -55,7 +55,7 @@ class BOTAN_DLL OID : public ASN1_Object
       /**
       * Add a component to this OID.
       * @param new_comp the new component to add to the end of this OID
-      * @return a reference to *this
+      * @return reference to *this
       */
       OID& operator+=(u32bit new_comp);
 
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/block_cipher.h b/src/block/block_cipher.h
index 73c72a9e4..c1b58996e 100644
--- a/src/block/block_cipher.h
+++ b/src/block/block_cipher.h
@@ -40,12 +40,12 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
       const u32bit BLOCK_SIZE;
 
       /**
-      * @return the native parallelism of this cipher in blocks
+      * @return native parallelism of this cipher in blocks
       */
       virtual u32bit parallelism() const { return 1; }
 
       /**
-      * @return the prefererred parallelism of this cipher in bytes
+      * @return prefererred parallelism of this cipher in bytes
       */
       u32bit parallel_bytes() const
          {
diff --git a/src/block/gost_28147/gost_28147.h b/src/block/gost_28147/gost_28147.h
index dbea932a0..ec23466f4 100644
--- a/src/block/gost_28147/gost_28147.h
+++ b/src/block/gost_28147/gost_28147.h
@@ -24,7 +24,7 @@ class BOTAN_DLL GOST_28147_89_Params
       /**
       * @param row the row
       * @param col the column
-      * @return the sbox entry at this row/column
+      * @return sbox entry at this row/column
       */
       byte sbox_entry(u32bit row, u32bit col) const;
 
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/botan.doxy.in b/src/build-data/botan.doxy.in
index b23bd892d..2f76a756b 100644
--- a/src/build-data/botan.doxy.in
+++ b/src/build-data/botan.doxy.in
@@ -21,7 +21,6 @@ SHORT_NAMES            = NO
 JAVADOC_AUTOBRIEF      = NO
 QT_AUTOBRIEF           = NO
 MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = NO
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 8
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/cert/cvc/eac_asn_obj.h b/src/cert/cvc/eac_asn_obj.h
index 9eaf02f63..d0bab6fdd 100644
--- a/src/cert/cvc/eac_asn_obj.h
+++ b/src/cert/cvc/eac_asn_obj.h
@@ -26,13 +26,13 @@ class BOTAN_DLL EAC_Time : public ASN1_Object
 
       /**
       * Get a this objects value as a string.
-      * @return the date string
+      * @return date string
       */
       std::string as_string() const;
 
       /**
       * Get a this objects value as a readable formatted string.
-      * @return the date string
+      * @return date string
       */
       std::string readable_string() const;
 
@@ -72,19 +72,19 @@ class BOTAN_DLL EAC_Time : public ASN1_Object
 
       /**
       * Get the year value of this objects.
-      * @return the year value
+      * @return year value
       */
       u32bit get_year() const;
 
       /**
       * Get the month value of this objects.
-      * @return the month value
+      * @return month value
       */
       u32bit get_month() const;
 
       /**
       * Get the day value of this objects.
-      * @return the day value
+      * @return day value
       */
       u32bit get_day() const;
 
@@ -174,13 +174,13 @@ class BOTAN_DLL ASN1_EAC_String: public ASN1_Object
 
       /**
       * Get this objects string value.
-      * @return the string value
+      * @return string value
       */
       std::string value() const;
 
       /**
       * Get this objects string value.
-      * @return the string value in iso8859 encoding
+      * @return string value in iso8859 encoding
       */
       std::string iso_8859() const;
 
diff --git a/src/cert/cvc/signed_obj.h b/src/cert/cvc/signed_obj.h
index c0ae2cfc5..0c0fb30af 100644
--- a/src/cert/cvc/signed_obj.h
+++ b/src/cert/cvc/signed_obj.h
@@ -24,7 +24,7 @@ class BOTAN_DLL EAC_Signed_Object
    public:
       /**
       * Get the TBS (to-be-signed) data in this object.
-      * @return the DER encoded TBS data of this object
+      * @return DER encoded TBS data of this object
       */
       virtual SecureVector<byte> tbs_data() const = 0;
 
@@ -32,7 +32,7 @@ class BOTAN_DLL EAC_Signed_Object
       * Get the signature of this object as a concatenation, i.e. if the
       * signature consists of multiple parts (like in the case of ECDSA)
       * these will be concatenated.
-      * @return the signature as a concatenation of its parts
+      * @return signature as a concatenation of its parts
       */
 
       /*
@@ -67,13 +67,13 @@ class BOTAN_DLL EAC_Signed_Object
 
       /**
       * BER encode this object.
-      * @return the result containing the BER representation of this object.
+      * @return result containing the BER representation of this object.
       */
       SecureVector<byte> BER_encode() const;
 
       /**
       * PEM encode this object.
-      * @return the result containing the PEM representation of this object.
+      * @return result containing the PEM representation of this object.
       */
       std::string PEM_encode() const;
 
diff --git a/src/cert/x509/crl_ent.h b/src/cert/x509/crl_ent.h
index 2b06189e4..ec90750db 100644
--- a/src/cert/x509/crl_ent.h
+++ b/src/cert/x509/crl_ent.h
@@ -23,19 +23,19 @@ class BOTAN_DLL CRL_Entry : public ASN1_Object
 
       /**
       * Get the serial number of the certificate associated with this entry.
-      * @return the certificate's serial number
+      * @return certificate's serial number
       */
       MemoryVector<byte> serial_number() const { return serial; }
 
       /**
       * Get the revocation date of the certificate associated with this entry
-      * @return the certificate's revocation date
+      * @return certificate's revocation date
       */
       X509_Time expire_time() const { return time; }
 
       /**
       * Get the entries reason code
-      * @return the reason code
+      * @return reason code
       */
       CRL_Code reason_code() const { return reason; }
 
diff --git a/src/cert/x509/pkcs10.h b/src/cert/x509/pkcs10.h
index 9b435de52..d1be9e0d3 100644
--- a/src/cert/x509/pkcs10.h
+++ b/src/cert/x509/pkcs10.h
@@ -23,38 +23,38 @@ class BOTAN_DLL PKCS10_Request : public X509_Object
    public:
       /**
       * Get the subject public key.
-      * @return the subject public key
+      * @return subject public key
       */
       Public_Key* subject_public_key() const;
 
       /**
       * Get the raw DER encoded public key.
-      * @return the raw DER encoded public key
+      * @return raw DER encoded public key
       */
       MemoryVector<byte> raw_public_key() const;
 
       /**
       * Get the subject DN.
-      * @return the subject DN
+      * @return subject DN
       */
       X509_DN subject_dn() const;
 
       /**
       * Get the subject alternative name.
-      * @return the subject alternative name.
+      * @return subject alternative name.
       */
       AlternativeName subject_alt_name() const;
 
       /**
       * Get the key constraints for the key associated with this
       * PKCS#10 object.
-      * @return the key constraints
+      * @return key constraints
       */
       Key_Constraints constraints() const;
 
       /**
       * Get the extendend key constraints (if any).
-      * @return the extended key constraints
+      * @return extended key constraints
       */
       std::vector<OID> ex_constraints() const;
 
@@ -67,13 +67,13 @@ class BOTAN_DLL PKCS10_Request : public X509_Object
       /**
       * Return the constraint on the path length defined
       * in the BasicConstraints extension.
-      * @return the path limit
+      * @return path limit
       */
       u32bit path_limit() const;
 
       /**
       * Get the challenge password for this request
-      * @return the challenge password for this request
+      * @return challenge password for this request
       */
       std::string challenge_password() const;
 
diff --git a/src/cert/x509/x509_ca.h b/src/cert/x509/x509_ca.h
index 6f36444ee..97be6a415 100644
--- a/src/cert/x509/x509_ca.h
+++ b/src/cert/x509/x509_ca.h
@@ -30,7 +30,7 @@ class BOTAN_DLL X509_CA
       * @param rng the rng to use
       * @param not_before the starting time for the certificate
       * @param not_after the expiration time for the certificate
-      * @return the resulting certificate
+      * @return resulting certificate
       */
       X509_Certificate sign_request(const PKCS10_Request& req,
                                     RandomNumberGenerator& rng,
@@ -39,7 +39,7 @@ class BOTAN_DLL X509_CA
 
       /**
       * Get the certificate of this CA.
-      * @return the CA certificate
+      * @return CA certificate
       */
       X509_Certificate ca_certificate() const;
 
@@ -48,7 +48,7 @@ class BOTAN_DLL X509_CA
       * @param rng the random number generator to use
       * @param next_update the time to set in next update in seconds
       * as the offset from the current time
-      * @return the new CRL
+      * @return new CRL
       */
       X509_CRL new_crl(RandomNumberGenerator& rng,
                        u32bit next_update = 0) const;
diff --git a/src/cert/x509/x509_crl.h b/src/cert/x509/x509_crl.h
index 74427fbef..c2b3c4f5c 100644
--- a/src/cert/x509/x509_crl.h
+++ b/src/cert/x509/x509_crl.h
@@ -31,13 +31,13 @@ class BOTAN_DLL X509_CRL : public X509_Object
 
       /**
       * Get the entries of this CRL in the form of a vector.
-      * @return a vector containing the entries of this CRL.
+      * @return vector containing the entries of this CRL.
       */
       std::vector<CRL_Entry> get_revoked() const;
 
       /**
       * Get the issuer DN of this CRL.
-      * @return the CRLs issuer DN
+      * @return CRLs issuer DN
       */
       X509_DN issuer_dn() const;
 
@@ -49,19 +49,19 @@ class BOTAN_DLL X509_CRL : public X509_Object
 
       /**
       * Get the serial number of this CRL.
-      * @return the CRLs serial number
+      * @return CRLs serial number
       */
       u32bit crl_number() const;
 
       /**
       * Get the CRL's thisUpdate value.
-      * @return the CRLs thisUpdate
+      * @return CRLs thisUpdate
       */
       X509_Time this_update() const;
 
       /**
       * Get the CRL's nextUpdate value.
-      * @return the CRLs nextdUpdate
+      * @return CRLs nextdUpdate
       */
       X509_Time next_update() const;
 
diff --git a/src/cert/x509/x509_obj.h b/src/cert/x509/x509_obj.h
index c7f92fa9d..52b76d218 100644
--- a/src/cert/x509/x509_obj.h
+++ b/src/cert/x509/x509_obj.h
@@ -33,7 +33,7 @@ class BOTAN_DLL X509_Object
       * @param rng the random number generator to use
       * @param alg_id the algorithm identifier of the signature scheme
       * @param tbs the tbs bits to be signed
-      * @return the signed X509 object
+      * @return signed X509 object
       */
       static MemoryVector<byte> make_signed(class PK_Signer* signer,
                                             RandomNumberGenerator& rng,
diff --git a/src/cert/x509/x509cert.h b/src/cert/x509/x509cert.h
index 4a9d11f7f..dc7ef4dbb 100644
--- a/src/cert/x509/x509cert.h
+++ b/src/cert/x509/x509cert.h
@@ -24,19 +24,19 @@ class BOTAN_DLL X509_Certificate : public X509_Object
    public:
      /**
      * Get the public key associated with this certificate.
-     * @return the subject public key of this certificate
+     * @return subject public key of this certificate
      */
       Public_Key* subject_public_key() const;
 
       /**
       * Get the issuer certificate DN.
-      * @return the issuer DN of this certificate
+      * @return issuer DN of this certificate
       */
       X509_DN issuer_dn() const;
 
       /**
       * Get the subject certificate DN.
-      * @return the subject DN of this certificate
+      * @return subject DN of this certificate
       */
       X509_DN subject_dn() const;
 
@@ -50,7 +50,7 @@ class BOTAN_DLL X509_Certificate : public X509_Object
       * "X509v3.BasicConstraints.is_ca", "X509v3.ExtendedKeyUsage",
       * "X509v3.CertificatePolicies", "X509v3.SubjectKeyIdentifier" or
       * "X509.Certificate.serial".
-      * @return the value(s) of the specified parameter
+      * @return value(s) of the specified parameter
       */
       std::vector<std::string> subject_info(const std::string& name) const;
 
@@ -58,43 +58,43 @@ class BOTAN_DLL X509_Certificate : public X509_Object
       * Get a value for a specific subject_info parameter name.
       * @param name the name of the paramter to look up. Possible names are
       * "X509.Certificate.v2.key_id" or "X509v3.AuthorityKeyIdentifier".
-      * @return the value(s) of the specified parameter
+      * @return value(s) of the specified parameter
       */
       std::vector<std::string> issuer_info(const std::string& name) const;
 
       /**
       * Get the notBefore of the certificate.
-      * @return the notBefore of the certificate
+      * @return notBefore of the certificate
       */
       std::string start_time() const;
 
       /**
       * Get the notAfter of the certificate.
-      * @return the notAfter of the certificate
+      * @return notAfter of the certificate
       */
       std::string end_time() const;
 
       /**
       * Get the X509 version of this certificate object.
-      * @return the X509 version
+      * @return X509 version
       */
       u32bit x509_version() const;
 
       /**
       * Get the serial number of this certificate.
-      * @return the certificates serial number
+      * @return certificates serial number
       */
       MemoryVector<byte> serial_number() const;
 
       /**
       * Get the DER encoded AuthorityKeyIdentifier of this certificate.
-      * @return the DER encoded AuthorityKeyIdentifier
+      * @return DER encoded AuthorityKeyIdentifier
       */
       MemoryVector<byte> authority_key_id() const;
 
       /**
       * Get the DER encoded SubjectKeyIdentifier of this certificate.
-      * @return the DER encoded SubjectKeyIdentifier
+      * @return DER encoded SubjectKeyIdentifier
       */
       MemoryVector<byte> subject_key_id() const;
 
@@ -113,14 +113,14 @@ class BOTAN_DLL X509_Certificate : public X509_Object
       /**
       * Get the path limit as defined in the BasicConstraints extension of
       * this certificate.
-      * @return the path limit
+      * @return path limit
       */
       u32bit path_limit() const;
 
       /**
       * Get the key constraints as defined in the KeyUsage extension of this
       * certificate.
-      * @return the key constraints
+      * @return key constraints
       */
       Key_Constraints constraints() const;
 
@@ -128,14 +128,14 @@ class BOTAN_DLL X509_Certificate : public X509_Object
       * Get the key constraints as defined in the ExtendedKeyUsage
       * extension of this
       * certificate.
-      * @return the key constraints
+      * @return key constraints
       */
       std::vector<std::string> ex_constraints() const;
 
       /**
       * Get the policies as defined in the CertificatePolicies extension
       * of this certificate.
-      * @return the certificate policies
+      * @return certificate policies
       */
       std::vector<std::string> policies() const;
 
diff --git a/src/cert/x509/x509self.h b/src/cert/x509/x509self.h
index 741350067..df5731050 100644
--- a/src/cert/x509/x509self.h
+++ b/src/cert/x509/x509self.h
@@ -174,7 +174,7 @@ namespace X509 {
 * associated with this self-signed certificate
 * @param hash_fn the hash function to use
 * @param rng the rng to use
-* @return the newly created self-signed certificate
+* @return newly created self-signed certificate
 */
 BOTAN_DLL X509_Certificate
 create_self_signed_cert(const X509_Cert_Options& opts,
@@ -188,7 +188,7 @@ create_self_signed_cert(const X509_Cert_Options& opts,
 * @param key the key used to sign this request
 * @param rng the rng to use
 * @param hash_fn the hash function to use
-* @return the newly created PKCS#10 request
+* @return newly created PKCS#10 request
 */
 BOTAN_DLL PKCS10_Request create_cert_req(const X509_Cert_Options& opts,
                                          const Private_Key& key,
diff --git a/src/engine/engine.cpp b/src/engine/engine.cpp
new file mode 100644
index 000000000..958d4148f
--- /dev/null
+++ b/src/engine/engine.cpp
@@ -0,0 +1,84 @@
+/*
+* Engine
+* (C) 2010 Jack Lloyd
+*
+* Distributed under the terms of the Botan license
+*/
+
+#include <botan/engine.h>
+
+namespace Botan {
+
+BlockCipher*
+Engine::find_block_cipher(const SCAN_Name&,
+                          Algorithm_Factory&) const
+   {
+   return 0;
+   }
+
+StreamCipher*
+Engine::find_stream_cipher(const SCAN_Name&,
+                           Algorithm_Factory&) const
+   {
+   return 0;
+   }
+
+HashFunction*
+Engine::find_hash(const SCAN_Name&,
+                  Algorithm_Factory&) const
+   {
+   return 0;
+   }
+
+MessageAuthenticationCode*
+Engine::find_mac(const SCAN_Name&,
+                 Algorithm_Factory&) const
+   {
+   return 0;
+   }
+
+Modular_Exponentiator*
+Engine::mod_exp(const BigInt&,
+                Power_Mod::Usage_Hints) const
+   {
+   return 0;
+   }
+
+Keyed_Filter* Engine::get_cipher(const std::string&,
+                                 Cipher_Dir,
+                                 Algorithm_Factory&)
+   {
+   return 0;
+   }
+
+PK_Ops::Key_Agreement*
+Engine::get_key_agreement_op(const Private_Key&) const
+   {
+   return 0;
+   }
+
+PK_Ops::Signature*
+Engine::get_signature_op(const Private_Key&) const
+   {
+   return 0;
+   }
+
+PK_Ops::Verification*
+Engine::get_verify_op(const Public_Key&) const
+   {
+   return 0;
+   }
+
+PK_Ops::Encryption*
+Engine::get_encryption_op(const Public_Key&) const
+   {
+   return 0;
+   }
+
+PK_Ops::Decryption*
+Engine::get_decryption_op(const Private_Key&) const
+   {
+   return 0;
+   }
+
+}
diff --git a/src/engine/engine.h b/src/engine/engine.h
index 6e8133692..c9bcd6126 100644
--- a/src/engine/engine.h
+++ b/src/engine/engine.h
@@ -27,7 +27,10 @@ class Algorithm_Factory;
 class Keyed_Filter;
 
 /**
-* Engine Base Class
+* Base class for all engines. All non-pure virtual functions simply
+* return NULL, indicating the algorithm in question is not
+* supported. Subclasses can reimplement whichever function(s)
+* they want to hook in a particular type.
 */
 class BOTAN_DLL Engine
    {
@@ -46,8 +49,7 @@ class BOTAN_DLL Engine
       */
       virtual BlockCipher*
          find_block_cipher(const SCAN_Name& algo_spec,
-                           Algorithm_Factory& af) const
-         { return 0; }
+                           Algorithm_Factory& af) const;
 
       /**
       * @param algo_spec the algorithm name/specification
@@ -56,8 +58,7 @@ class BOTAN_DLL Engine
       */
       virtual StreamCipher*
          find_stream_cipher(const SCAN_Name& algo_spec,
-                            Algorithm_Factory& af) const
-         { return 0; }
+                            Algorithm_Factory& af) const;
 
       /**
       * @param algo_spec the algorithm name/specification
@@ -66,8 +67,7 @@ class BOTAN_DLL Engine
       */
       virtual HashFunction*
          find_hash(const SCAN_Name& algo_spec,
-                   Algorithm_Factory& af) const
-         { return 0; }
+                   Algorithm_Factory& af) const;
 
       /**
       * @param algo_spec the algorithm name/specification
@@ -76,8 +76,7 @@ class BOTAN_DLL Engine
       */
       virtual MessageAuthenticationCode*
          find_mac(const SCAN_Name& algo_spec,
-                  Algorithm_Factory& af) const
-         { return 0; }
+                  Algorithm_Factory& af) const;
 
       /**
       * @param n the modulus
@@ -86,8 +85,7 @@ class BOTAN_DLL Engine
       */
       virtual Modular_Exponentiator*
          mod_exp(const BigInt& n,
-                 Power_Mod::Usage_Hints hints) const
-         { return 0; }
+                 Power_Mod::Usage_Hints hints) const;
 
       /**
       * Return a new cipher object
@@ -98,8 +96,7 @@ class BOTAN_DLL Engine
       */
       virtual Keyed_Filter* get_cipher(const std::string& algo_spec,
                                        Cipher_Dir dir,
-                                       Algorithm_Factory& af)
-         { return 0; }
+                                       Algorithm_Factory& af);
 
       /**
       * Return a new operator object for this key, if possible
@@ -107,10 +104,7 @@ class BOTAN_DLL Engine
       * @return newly allocated operator object, or NULL
       */
       virtual PK_Ops::Key_Agreement*
-         get_key_agreement_op(const Private_Key& key) const
-         {
-         return 0;
-         }
+         get_key_agreement_op(const Private_Key& key) const;
 
       /**
       * Return a new operator object for this key, if possible
@@ -118,10 +112,7 @@ class BOTAN_DLL Engine
       * @return newly allocated operator object, or NULL
       */
       virtual PK_Ops::Signature*
-         get_signature_op(const Private_Key& key) const
-         {
-         return 0;
-         }
+         get_signature_op(const Private_Key& key) const;
 
       /**
       * Return a new operator object for this key, if possible
@@ -129,10 +120,7 @@ class BOTAN_DLL Engine
       * @return newly allocated operator object, or NULL
       */
       virtual PK_Ops::Verification*
-         get_verify_op(const Public_Key& key) const
-         {
-         return 0;
-         }
+         get_verify_op(const Public_Key& key) const;
 
       /**
       * Return a new operator object for this key, if possible
@@ -140,10 +128,7 @@ class BOTAN_DLL Engine
       * @return newly allocated operator object, or NULL
       */
       virtual PK_Ops::Encryption*
-         get_encryption_op(const Public_Key& key) const
-         {
-         return 0;
-         }
+         get_encryption_op(const Public_Key& key) const;
 
       /**
       * Return a new operator object for this key, if possible
@@ -151,10 +136,7 @@ class BOTAN_DLL Engine
       * @return newly allocated operator object, or NULL
       */
       virtual PK_Ops::Decryption*
-         get_decryption_op(const Private_Key& key) const
-         {
-         return 0;
-         }
+         get_decryption_op(const Private_Key& key) const;
    };
 
 }
diff --git a/src/engine/info.txt b/src/engine/info.txt
index 32fcf21c2..5f787cebe 100644
--- a/src/engine/info.txt
+++ b/src/engine/info.txt
@@ -4,6 +4,10 @@ define ENGINES
 engine.h
 </header:public>
 
+<source>
+engine.cpp
+</source>
+
 <requires>
 block
 hash
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/filters/basefilt.cpp b/src/filters/basefilt.cpp
index c91a5aa62..bf9a526df 100644
--- a/src/filters/basefilt.cpp
+++ b/src/filters/basefilt.cpp
@@ -6,9 +6,16 @@
 */
 
 #include <botan/basefilt.h>
+#include <botan/key_filt.h>
+
+#include <assert.h>
 
 namespace Botan {
 
+void Keyed_Filter::set_iv(const InitializationVector&)
+   {
+   }
+
 /*
 * Chain Constructor
 */
diff --git a/src/filters/data_src.h b/src/filters/data_src.h
index c69aa84b0..bf3bfa99b 100644
--- a/src/filters/data_src.h
+++ b/src/filters/data_src.h
@@ -26,7 +26,7 @@ class BOTAN_DLL DataSource
       *
       * @param out the byte array to write the result to
       * @param length the length of the byte array out
-      * @return the length in bytes that was actually read and put
+      * @return length in bytes that was actually read and put
       * into out
       */
       virtual u32bit read(byte out[], u32bit length) = 0;
@@ -39,7 +39,7 @@ class BOTAN_DLL DataSource
       * @param out the byte array to write the output to
       * @param length the length of the byte array out
       * @param peek_offset the offset into the stream to read at
-      * @return the length in bytes that was actually read and put
+      * @return length in bytes that was actually read and put
       * into out
       */
       virtual u32bit peek(byte out[], u32bit length,
@@ -59,7 +59,7 @@ class BOTAN_DLL DataSource
       /**
       * Read one byte.
       * @param out the byte to read to
-      * @return the length in bytes that was actually read and put
+      * @return length in bytes that was actually read and put
       * into out
       */
       u32bit read_byte(byte& out);
@@ -67,7 +67,7 @@ class BOTAN_DLL DataSource
       /**
       * Peek at one byte.
       * @param out an output byte
-      * @return the length in bytes that was actually read and put
+      * @return length in bytes that was actually read and put
       * into out
       */
       u32bit peek_byte(byte& out) const;
@@ -75,7 +75,7 @@ class BOTAN_DLL DataSource
       /**
       * Discard the next N bytes of the data
       * @param N the number of bytes to discard
-      * @return the number of bytes actually discarded
+      * @return number of bytes actually discarded
       */
       u32bit discard_next(u32bit N);
 
diff --git a/src/filters/key_filt.h b/src/filters/key_filt.h
index 6f3d23fcd..5b34751b4 100644
--- a/src/filters/key_filt.h
+++ b/src/filters/key_filt.h
@@ -30,7 +30,7 @@ class BOTAN_DLL Keyed_Filter : public Filter
       * Set the initialization vector of this filter.
       * @param iv the initialization vector to set
       */
-      virtual void set_iv(const InitializationVector& iv) {}
+      virtual void set_iv(const InitializationVector& iv);
 
       /**
       * Check whether a key length is valid for this filter.
diff --git a/src/filters/pipe.h b/src/filters/pipe.h
index 4f66b51d9..b7f09199b 100644
--- a/src/filters/pipe.h
+++ b/src/filters/pipe.h
@@ -116,7 +116,7 @@ class BOTAN_DLL Pipe : public DataSource
       * Find out how many bytes are ready to read.
       * @param msg the number identifying the message
       * for which the information is desired
-      * @return the number of bytes that can still be read
+      * @return number of bytes that can still be read
       */
       u32bit remaining(message_id msg = DEFAULT_MESSAGE) const;
 
@@ -127,7 +127,7 @@ class BOTAN_DLL Pipe : public DataSource
       *
       * @param output the byte array to write the read bytes to
       * @param length the length of the byte array output
-      * @return the number of bytes actually read into output
+      * @return number of bytes actually read into output
       */
       u32bit read(byte output[], u32bit length);
 
@@ -138,7 +138,7 @@ class BOTAN_DLL Pipe : public DataSource
       * @param output the byte array to write the read bytes to
       * @param length the length of the byte array output
       * @param msg the number identifying the message to read from
-      * @return the number of bytes actually read into output
+      * @return number of bytes actually read into output
       */
       u32bit read(byte output[], u32bit length, message_id msg);
 
@@ -149,21 +149,21 @@ class BOTAN_DLL Pipe : public DataSource
       *
       * @param output the byte to write the result to
       * @param msg the message to read from
-      * @return the number of bytes actually read into output
+      * @return number of bytes actually read into output
       */
       u32bit read(byte& output, message_id msg = DEFAULT_MESSAGE);
 
       /**
       * Read the full contents of the pipe.
       * @param msg the number identifying the message to read from
-      * @return a SecureVector holding the contents of the pipe
+      * @return SecureVector holding the contents of the pipe
       */
       SecureVector<byte> read_all(message_id msg = DEFAULT_MESSAGE);
 
       /**
       * Read the full contents of the pipe.
       * @param msg the number identifying the message to read from
-      * @return a string holding the contents of the pipe
+      * @return string holding the contents of the pipe
       */
       std::string read_all_as_string(message_id = DEFAULT_MESSAGE);
 
@@ -173,7 +173,7 @@ class BOTAN_DLL Pipe : public DataSource
       * @param output the byte array to write the peeked message part to
       * @param length the length of the byte array output
       * @param offset the offset from the current position in message
-      * @return the number of bytes actually peeked and written into output
+      * @return number of bytes actually peeked and written into output
       */
       u32bit peek(byte output[], u32bit length, u32bit offset) const;
 
@@ -184,7 +184,7 @@ class BOTAN_DLL Pipe : public DataSource
       * @param length the length of the byte array output
       * @param offset the offset from the current position in message
       * @param msg the number identifying the message to peek from
-      * @return the number of bytes actually peeked and written into output
+      * @return number of bytes actually peeked and written into output
       */
       u32bit peek(byte output[], u32bit length,
                   u32bit offset, message_id msg) const;
@@ -195,7 +195,7 @@ class BOTAN_DLL Pipe : public DataSource
       * @param output the byte to write the peeked message byte to
       * @param offset the offset from the current position in message
       * @param msg the number identifying the message to peek from
-      * @return the number of bytes actually peeked and written into output
+      * @return number of bytes actually peeked and written into output
       */
       u32bit peek(byte& output, u32bit offset,
                   message_id msg = DEFAULT_MESSAGE) const;
@@ -214,7 +214,7 @@ class BOTAN_DLL Pipe : public DataSource
 
       /**
       * Get the number of messages the are in this pipe.
-      * @return the number of messages the are in this pipe
+      * @return number of messages the are in this pipe
       */
       message_id message_count() const;
 
diff --git a/src/hash/hash.h b/src/hash/hash.h
index 4f753f765..cdf90f184 100644
--- a/src/hash/hash.h
+++ b/src/hash/hash.h
@@ -31,7 +31,7 @@ class BOTAN_DLL HashFunction : public BufferedComputation
 
       /**
       * Get the name of this algorithm.
-      * @return the name of this algorithm
+      * @return name of this algorithm
       */
       virtual std::string name() const = 0;
 
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/libstate.h b/src/libstate/libstate.h
index d7fb6e02c..eeb38287a 100644
--- a/src/libstate/libstate.h
+++ b/src/libstate/libstate.h
@@ -35,12 +35,12 @@ class BOTAN_DLL Library_State
       void initialize(bool thread_safe);
 
       /**
-      * @return the global Algorithm_Factory
+      * @return global Algorithm_Factory
       */
       Algorithm_Factory& algorithm_factory() const;
 
       /**
-      * @return the global RandomNumberGenerator
+      * @return global RandomNumberGenerator
       */
       RandomNumberGenerator& global_rng();
 
@@ -111,7 +111,7 @@ class BOTAN_DLL Library_State
       std::string deref_alias(const std::string& alias) const;
 
       /**
-      * @return a newly created Mutex (free with delete)
+      * @return newly created Mutex (free with delete)
       */
       Mutex* get_mutex() const;
    private:
@@ -155,7 +155,7 @@ BOTAN_DLL void set_global_state(Library_State* state);
 /**
 * Swap the current state for another
 * @param new_state the new state object to use
-* @return the previous state (or NULL if none)
+* @return previous state (or NULL if none)
 */
 BOTAN_DLL Library_State* swap_global_state(Library_State* new_state);
 
diff --git a/src/libstate/look_pk.h b/src/libstate/look_pk.h
index e1dc1d95c..c980e5f8d 100644
--- a/src/libstate/look_pk.h
+++ b/src/libstate/look_pk.h
@@ -19,7 +19,7 @@ namespace Botan {
 *
 * @param key the key that will work inside the encryptor
 * @param eme determines the algorithm and encoding
-* @return the public key encryptor object
+* @return public key encryptor object
 */
 inline PK_Encryptor* get_pk_encryptor(const Public_Key& key,
                                       const std::string& eme)
@@ -33,7 +33,7 @@ inline PK_Encryptor* get_pk_encryptor(const Public_Key& key,
 *
 * @param key the key that will work inside the decryptor
 * @param eme determines the algorithm and encoding
-* @return the public key decryptor object
+* @return public key decryptor object
 */
 inline PK_Decryptor* get_pk_decryptor(const Private_Key& key,
                                       const std::string& eme)
@@ -48,7 +48,7 @@ inline PK_Decryptor* get_pk_decryptor(const Private_Key& key,
 * @param key the key that will work inside the signer
 * @param emsa determines the algorithm, encoding and hash algorithm
 * @param sig_format the signature format to be used
-* @return the public key signer object
+* @return public key signer object
 */
 inline PK_Signer* get_pk_signer(const Private_Key& key,
                                 const std::string& emsa,
@@ -64,7 +64,7 @@ inline PK_Signer* get_pk_signer(const Private_Key& key,
 * @param key the key that will work inside the verifier
 * @param emsa determines the algorithm, encoding and hash algorithm
 * @param sig_format the signature format to be used
-* @return the public key verifier object
+* @return public key verifier object
 */
 inline PK_Verifier* get_pk_verifier(const Public_Key& key,
                                     const std::string& emsa,
@@ -79,7 +79,7 @@ inline PK_Verifier* get_pk_verifier(const Public_Key& key,
 *
 * @param key the key that will work inside the key agreement
 * @param kdf the kdf algorithm to use
-* @return the key agreement algorithm
+* @return key agreement algorithm
 */
 inline PK_Key_Agreement* get_pk_kas(const PK_Key_Agreement_Key& key,
                                        const std::string& kdf)
diff --git a/src/libstate/lookup.h b/src/libstate/lookup.h
index aa3a65f96..76e06b2de 100644
--- a/src/libstate/lookup.h
+++ b/src/libstate/lookup.h
@@ -64,7 +64,7 @@ retrieve_mac(const std::string& algo_spec)
 * @deprecated Call algorithm_factory() directly
 *
 * @param algo_spec the name of the desired block cipher
-* @return a pointer to the block cipher object
+* @return pointer to the block cipher object
 */
 inline BlockCipher* get_block_cipher(const std::string& algo_spec)
    {
@@ -77,7 +77,7 @@ inline BlockCipher* get_block_cipher(const std::string& algo_spec)
 * @deprecated Call algorithm_factory() directly
 *
 * @param algo_spec the name of the desired stream cipher
-* @return a pointer to the stream cipher object
+* @return pointer to the stream cipher object
 */
 inline StreamCipher* get_stream_cipher(const std::string& algo_spec)
    {
@@ -90,7 +90,7 @@ inline StreamCipher* get_stream_cipher(const std::string& algo_spec)
 * @deprecated Call algorithm_factory() directly
 *
 * @param algo_spec the name of the desired hash function
-* @return a pointer to the hash function object
+* @return pointer to the hash function object
 */
 inline HashFunction* get_hash(const std::string& algo_spec)
    {
@@ -103,7 +103,7 @@ inline HashFunction* get_hash(const std::string& algo_spec)
 * @deprecated Call algorithm_factory() directly
 *
 * @param algo_spec the name of the desired MAC
-* @return a pointer to the MAC object
+* @return pointer to the MAC object
 */
 inline MessageAuthenticationCode* get_mac(const std::string& algo_spec)
    {
@@ -114,7 +114,7 @@ inline MessageAuthenticationCode* get_mac(const std::string& algo_spec)
 /**
 * String to key algorithm factory method.
 * @param algo_spec the name of the desired string to key (S2K) algorithm
-* @return a pointer to the string to key algorithm object
+* @return pointer to the string to key algorithm object
 */
 BOTAN_DLL S2K* get_s2k(const std::string& algo_spec);
 
@@ -127,7 +127,7 @@ BOTAN_DLL S2K* get_s2k(const std::string& algo_spec);
 /**
 * Factory method for EME (message-encoding methods for encryption) objects
 * @param algo_spec the name of the EME to create
-* @return a pointer to the desired EME object
+* @return pointer to the desired EME object
 */
 BOTAN_DLL EME*  get_eme(const std::string& algo_spec);
 
@@ -135,14 +135,14 @@ BOTAN_DLL EME*  get_eme(const std::string& algo_spec);
 * Factory method for EMSA (message-encoding methods for signatures
 * with appendix) objects
 * @param algo_spec the name of the EME to create
-* @return a pointer to the desired EME object
+* @return pointer to the desired EME object
 */
 BOTAN_DLL EMSA* get_emsa(const std::string& algo_spec);
 
 /**
 * Factory method for KDF (key derivation function)
 * @param algo_spec the name of the KDF to create
-* @return a pointer to the desired KDF object
+* @return pointer to the desired KDF object
 */
 BOTAN_DLL KDF*  get_kdf(const std::string& algo_spec);
 
@@ -158,7 +158,7 @@ BOTAN_DLL KDF*  get_kdf(const std::string& algo_spec);
 * @param iv the initialization vector to be used
 * @param direction determines whether the filter will be an encrypting
 * or decrypting filter
-* @return a pointer to the encryption or decryption filter
+* @return pointer to the encryption or decryption filter
 */
 BOTAN_DLL Keyed_Filter* get_cipher(const std::string& algo_spec,
                                    const SymmetricKey& key,
@@ -172,7 +172,7 @@ BOTAN_DLL Keyed_Filter* get_cipher(const std::string& algo_spec,
 * the filter
 * @param direction determines whether the filter will be an encrypting
 * or decrypting filter
-* @return a pointer to the encryption or decryption filter
+* @return pointer to the encryption or decryption filter
 */
 BOTAN_DLL Keyed_Filter* get_cipher(const std::string& algo_spec,
                                    const SymmetricKey& key,
@@ -185,7 +185,7 @@ BOTAN_DLL Keyed_Filter* get_cipher(const std::string& algo_spec,
 * @param algo_spec the name of the desired cipher
 * @param direction determines whether the filter will be an encrypting or
 * decrypting filter
-* @return a pointer to the encryption or decryption filter
+* @return pointer to the encryption or decryption filter
 */
 BOTAN_DLL Keyed_Filter* get_cipher(const std::string& algo_spec,
                                    Cipher_Dir direction);
diff --git a/src/libstate/oid_lookup/oids.h b/src/libstate/oid_lookup/oids.h
index fdfe61f7c..70b7dee81 100644
--- a/src/libstate/oid_lookup/oids.h
+++ b/src/libstate/oid_lookup/oids.h
@@ -31,7 +31,7 @@ BOTAN_DLL bool have_oid(const std::string& oid);
 /**
 * Resolve an OID
 * @param oid the OID to look up
-* @return the name associated with this OID
+* @return name associated with this OID
 */
 BOTAN_DLL std::string lookup(const OID& oid);
 
@@ -39,7 +39,7 @@ BOTAN_DLL std::string lookup(const OID& oid);
 * Find the OID to a name. The lookup will be performed in the
 * general OID section of the configuration.
 * @param name the name to resolve
-* @return the OID associated with the specified name
+* @return OID associated with the specified name
 */
 BOTAN_DLL OID lookup(const std::string& name);
 
diff --git a/src/libstate/scan_name.h b/src/libstate/scan_name.h
index 66eda688c..3d11d54f6 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 original input string
       */
       std::string as_string() const { return orig_algo_spec; }
 
       /**
-      @return the algorithm name
+      * @return algorithm name
       */
       std::string algo_name() const { return alg_name; }
 
       /**
-      @return the algorithm name plus any arguments
+      * @return algorithm name plus any arguments
       */
       std::string algo_name_and_args() const;
 
       /**
-      @return the number of arguments
+      * @return 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 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 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 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 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 cipher mode padding (if any)
       */
       std::string cipher_mode_pad() const
          { return (mode_info.size() >= 2) ? mode_info[1] : ""; }
diff --git a/src/mac/mac.h b/src/mac/mac.h
index 52ff9c94c..4518d91ad 100644
--- a/src/mac/mac.h
+++ b/src/mac/mac.h
@@ -36,7 +36,7 @@ class BOTAN_DLL MessageAuthenticationCode : public BufferedComputation,
 
       /**
       * Get the name of this algorithm.
-      * @return the name of this algorithm
+      * @return name of this algorithm
       */
       virtual std::string name() const = 0;
 
diff --git a/src/math/bigint/bigint.h b/src/math/bigint/bigint.h
index cd1aebf00..971a7cc2c 100644
--- a/src/math/bigint/bigint.h
+++ b/src/math/bigint/bigint.h
@@ -44,90 +44,96 @@ class BOTAN_DLL BigInt
         { DivideByZero() : Exception("BigInt divide by zero") {} };
 
      /**
-     * += Operator
+     * += operator
      * @param y the BigInt to add to this
      */
      BigInt& operator+=(const BigInt& y);
 
      /**
-     * -= Operator
+     * -= operator
      * @param y the BigInt to subtract from this
      */
      BigInt& operator-=(const BigInt& y);
 
      /**
-     * *= Operator
+     * *= operator
      * @param y the BigInt to multiply with this
      */
      BigInt& operator*=(const BigInt& y);
 
      /**
-     * /= Operator
+     * /= operator
      * @param y the BigInt to divide this by
      */
      BigInt& operator/=(const BigInt& y);
 
      /**
-     * %= Operator, modulo operator.
+     * %= operator, modulo operator.
      * @param y the modulus to reduce this by
      */
      BigInt& operator%=(const BigInt& y);
 
      /**
-     * %= Operator
+     * %= operator
      * @param y the modulus (word) to reduce this by
      */
      word    operator%=(word y);
 
      /**
-     * <<= Operator
-     * @param y the amount of bits to shift this left
+     * <<= operator
+     * @param y the number of bits to shift this left by
      */
      BigInt& operator<<=(u32bit y);
 
      /**
-     * >>= Operator
-     * @param y the amount of bits to shift this right
+     * >>= operator
+     * @param y the number of bits to shift this right by
      */
      BigInt& operator>>=(u32bit y);
 
      /**
-     * ++ Operator
+     * Increment operator
      */
      BigInt& operator++() { return (*this += 1); }
 
      /**
-     * -- Operator
+     * Decrement operator
      */
      BigInt& operator--() { return (*this -= 1); }
 
      /**
-     * ++ Operator (postfix)
+     * ++ operator (postfix)
      */
      BigInt  operator++(int) { BigInt x = (*this); ++(*this); return x; }
 
      /**
-     * -- Operator (postfix)
+     * -- operator (postfix)
      */
      BigInt  operator--(int) { BigInt x = (*this); --(*this); return x; }
 
      /**
-     * Unary - Operator
+     * Unary negation operator
+     * @return negative this
      */
      BigInt operator-() const;
 
      /**
-     * ! Operator
+     * ! operator
+     * @return true iff this is zero, otherwise false
      */
      bool operator !() const { return (!is_nonzero()); }
 
      /**
-     * [] Operator (array access)
+     * [] operator (array access)
+     * @param i a word index
+     * @return the word at index i
      */
      word& operator[](u32bit i) { return reg[i]; }
 
      /**
-     * [] Operator (array access)
+     * [] operator (array access)
+     * @param i a word index
+     * @return the word at index i
      */
      word operator[](u32bit i) const { return reg[i]; }
 
@@ -137,8 +143,8 @@ class BOTAN_DLL BigInt
      void clear() { get_reg().clear(); }
 
      /**
-     * Compare *this to another BigInt.
-     * @param n the BigInt value to compare to this.
+     * Compare *this to another BigInt
+     * @param n the BigInt value to compare with
      * @param check_signs include sign in comparison?
      * @result if (this<n) return -1, if (this>n) return 1, if both
      * values are identical return 0 [like Perl's <=> operator]
@@ -158,7 +164,7 @@ class BOTAN_DLL BigInt
      bool is_odd()  const { return (get_bit(0) == 1); }
 
      /**
-     * Test if the integer is not zero.
+     * Test if the integer is not zero
      * @result true if the integer is non-zero, false otherwise
      */
      bool is_nonzero() const { return (!is_zero()); }
@@ -220,7 +226,7 @@ class BOTAN_DLL BigInt
      /**
      * Return the word at a specified position of the internal register
      * @param n position in the register
-     * @return the value at position n
+     * @return value at position n
      */
      word word_at(u32bit n) const
         { return ((n < size()) ? reg[n] : 0); }
@@ -371,7 +377,7 @@ class BOTAN_DLL BigInt
      * @param rng a random number generator
      * @param min the minimum value
      * @param max the maximum value
-     * @return a random integer between min and max
+     * @return random integer between min and max
      */
      static BigInt random_integer(RandomNumberGenerator& rng,
                                   const BigInt& min,
@@ -396,15 +402,22 @@ class BOTAN_DLL BigInt
 
      /**
      * Create a BigInt from an integer in a byte array
-     * @param buf the BigInt value to compare to this.
+     * @param buf the binary value to load
      * @param length size of buf
      * @param base number-base of the integer in buf
-     * @result BigInt-representing the given integer read from the byte array
+     * @result BigInt representing the integer in the byte array
      */
      static BigInt decode(const byte buf[], u32bit length,
                           Base base = Binary);
 
-     static BigInt decode(const MemoryRegion<byte>&, Base = Binary);
+     /**
+     * Create a BigInt from an integer in a byte array
+     * @param buf the binary value to load
+     * @param base number-base of the integer in buf
+     * @result BigInt representing the integer in the byte array
+     */
+     static BigInt decode(const MemoryRegion<byte>& buf,
+                          Base base = Binary);
 
      /**
      * Encode a BigInt to a byte array according to IEEE 1363
@@ -426,16 +439,16 @@ class BOTAN_DLL BigInt
      BigInt() { signedness = Positive; }
 
      /**
-     * Create BigInt from 64bit-Integer value
-     * @param n 64bit-integer
+     * Create BigInt from 64 bit integer
+     * @param n initial value of this BigInt
      */
      BigInt(u64bit n);
 
      /**
-     * Copy-Constructor: clone given BigInt
-     * @param bigint the BigInt to clone
+     * Copy Constructor
+     * @param other the BigInt to copy
      */
-     BigInt(const BigInt& bigint);
+     BigInt(const BigInt& other);
 
      /**
      * Create BigInt from a string.
@@ -451,9 +464,9 @@ class BOTAN_DLL BigInt
 
      /**
      * Create a BigInt from an integer in a byte array
-     * @param buf the BigInt value to compare to this.
+     * @param buf the byte array holding the value
      * @param length size of buf
-     * @param base number-base of the integer in buf
+     * @param base is the number base of the integer in buf
      */
      BigInt(const byte buf[], u32bit length, Base base = Binary);
 
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/pubkey/dl_algo/dl_algo.h b/src/pubkey/dl_algo/dl_algo.h
index 445f6c3f9..429bfb554 100644
--- a/src/pubkey/dl_algo/dl_algo.h
+++ b/src/pubkey/dl_algo/dl_algo.h
@@ -28,7 +28,7 @@ class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key
 
       /**
       * Get the DL domain parameters of this key.
-      * @return the DL domain parameters of this key
+      * @return DL domain parameters of this key
       */
       const DL_Group& get_domain() const { return group; }
 
@@ -39,25 +39,25 @@ class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key
 
       /**
       * Get the prime p of the underlying DL group.
-      * @return the prime p
+      * @return prime p
       */
       const BigInt& group_p() const { return group.get_p(); }
 
       /**
       * Get the prime q of the underlying DL group.
-      * @return the prime q
+      * @return prime q
       */
       const BigInt& group_q() const { return group.get_q(); }
 
       /**
       * Get the generator g of the underlying DL group.
-      * @return the generator g
+      * @return generator g
       */
       const BigInt& group_g() const { return group.get_g(); }
 
       /**
       * Get the underlying groups encoding format.
-      * @return the encoding format
+      * @return encoding format
       */
       virtual DL_Group::Format group_format() const = 0;
 
@@ -82,7 +82,7 @@ class BOTAN_DLL DL_Scheme_PrivateKey : public virtual DL_Scheme_PublicKey,
 
       /**
       * Get the secret key x.
-      * @return the secret key
+      * @return secret key
       */
       const BigInt& get_x() const { return x; }
 
diff --git a/src/pubkey/dl_group/dl_group.h b/src/pubkey/dl_group/dl_group.h
index a84a85f87..885ccd2f9 100644
--- a/src/pubkey/dl_group/dl_group.h
+++ b/src/pubkey/dl_group/dl_group.h
@@ -22,19 +22,19 @@ class BOTAN_DLL DL_Group
    public:
       /**
       * Get the prime p.
-      * @return the prime p
+      * @return prime p
       */
       const BigInt& get_p() const;
 
       /**
       * Get the prime q.
-      * @return the prime q
+      * @return prime q
       */
       const BigInt& get_q() const;
 
       /**
       * Get the base g.
-      * @return the base g
+      * @return base g
       */
       const BigInt& get_g() const;
 
@@ -68,14 +68,14 @@ class BOTAN_DLL DL_Group
       /**
       * Encode this group into a string using PEM encoding.
       * @param format the encoding format
-      * @return the string holding the PEM encoded group
+      * @return string holding the PEM encoded group
       */
       std::string PEM_encode(Format format) const;
 
       /**
       * Encode this group into a string using DER encoding.
       * @param format the encoding format
-      * @return the string holding the DER encoded group
+      * @return string holding the DER encoded group
       */
       SecureVector<byte> DER_encode(Format format) const;
 
diff --git a/src/pubkey/ecc_key/ecc_key.cpp b/src/pubkey/ecc_key/ecc_key.cpp
index 2c66dc97f..4f90fa321 100644
--- a/src/pubkey/ecc_key/ecc_key.cpp
+++ b/src/pubkey/ecc_key/ecc_key.cpp
@@ -24,9 +24,6 @@ EC_PublicKey::EC_PublicKey(const EC_Domain_Params& dom_par,
    {
    if(domain().get_curve() != public_point().get_curve())
       throw Invalid_Argument("EC_PublicKey: curve mismatch in constructor");
-
-   if(!public_point().on_the_curve())
-      throw Invalid_State("Public key was not on the curve");
    }
 
 EC_PublicKey::EC_PublicKey(const AlgorithmIdentifier& alg_id,
@@ -38,6 +35,12 @@ EC_PublicKey::EC_PublicKey(const AlgorithmIdentifier& alg_id,
    public_key = OS2ECP(key_bits, domain().get_curve());
    }
 
+bool EC_PublicKey::check_key(RandomNumberGenerator&,
+                             bool) const
+   {
+   return public_point().on_the_curve();
+   }
+
 AlgorithmIdentifier EC_PublicKey::algorithm_identifier() const
    {
    return AlgorithmIdentifier(get_oid(), DER_domain());
diff --git a/src/pubkey/ecc_key/ecc_key.h b/src/pubkey/ecc_key/ecc_key.h
index 92f02613c..8155543da 100644
--- a/src/pubkey/ecc_key/ecc_key.h
+++ b/src/pubkey/ecc_key/ecc_key.h
@@ -49,6 +49,9 @@ class BOTAN_DLL EC_PublicKey : public virtual Public_Key
 
       MemoryVector<byte> x509_subject_public_key() const;
 
+      bool check_key(RandomNumberGenerator& rng,
+                     bool strong) const;
+
       /**
       * Get the domain parameters of this key.
       * @throw Invalid_State is thrown if the
diff --git a/src/pubkey/ecdh/ecdh.h b/src/pubkey/ecdh/ecdh.h
index ea1205a48..f0872c5cc 100644
--- a/src/pubkey/ecdh/ecdh.h
+++ b/src/pubkey/ecdh/ecdh.h
@@ -46,12 +46,12 @@ class BOTAN_DLL ECDH_PublicKey : public virtual EC_PublicKey
       * Get the maximum number of bits allowed to be fed to this key.
       * This is the bitlength of the order of the base point.
 
-      * @return the maximum number of input bits
+      * @return maximum number of input bits
       */
       u32bit max_input_bits() const { return domain().get_order().bits(); }
 
       /**
-      * @return the public point value
+      * @return public point value
       */
       MemoryVector<byte> public_value() const
          { return EC2OSP(public_point(), PointGFp::UNCOMPRESSED); }
diff --git a/src/pubkey/if_algo/if_algo.h b/src/pubkey/if_algo/if_algo.h
index 764a99e13..d0a1ec197 100644
--- a/src/pubkey/if_algo/if_algo.h
+++ b/src/pubkey/if_algo/if_algo.h
@@ -34,12 +34,12 @@ class BOTAN_DLL IF_Scheme_PublicKey : public virtual Public_Key
       MemoryVector<byte> x509_subject_public_key() const;
 
       /**
-      * @return the public modulus
+      * @return public modulus
       */
       const BigInt& get_n() const { return n; }
 
       /**
-      * @return the public exponent
+      * @return public exponent
       */
       const BigInt& get_e() const { return e; }
 
@@ -73,13 +73,13 @@ class BOTAN_DLL IF_Scheme_PrivateKey : public virtual IF_Scheme_PublicKey,
 
       /**
       * Get the first prime p.
-      * @return the prime p
+      * @return prime p
       */
       const BigInt& get_p() const { return p; }
 
       /**
       * Get the second prime q.
-      * @return the prime q
+      * @return prime q
       */
       const BigInt& get_q() const { return q; }
 
diff --git a/src/pubkey/pk_keys.h b/src/pubkey/pk_keys.h
index e90fcf51a..8f086c617 100644
--- a/src/pubkey/pk_keys.h
+++ b/src/pubkey/pk_keys.h
@@ -23,13 +23,13 @@ class BOTAN_DLL Public_Key
    public:
       /**
       * Get the name of the underlying public key scheme.
-      * @return the name of the public key scheme
+      * @return name of the public key scheme
       */
       virtual std::string algo_name() const = 0;
 
       /**
       * Get the OID of the underlying public key scheme.
-      * @return the OID of the public key scheme
+      * @return OID of the public key scheme
       */
       virtual OID get_oid() const;
 
@@ -40,24 +40,24 @@ class BOTAN_DLL Public_Key
       * of the test
       * @return true if the test is passed
       */
-      virtual bool check_key(RandomNumberGenerator& rng, bool strong) const
-         { return true; }
+      virtual bool check_key(RandomNumberGenerator& rng,
+                             bool strong) const = 0;
 
       /**
       * Find out the number of message parts supported by this scheme.
-      * @return the number of message parts
+      * @return number of message parts
       */
       virtual u32bit message_parts() const { return 1; }
 
       /**
       * Find out the message part size supported by this scheme/key.
-      * @return the size of the message parts
+      * @return size of the message parts in bits
       */
       virtual u32bit message_part_size() const { return 0; }
 
       /**
       * Get the maximum message size in bits supported by this public key.
-      * @return the maximum message in bits
+      * @return maximum message size in bits
       */
       virtual u32bit max_input_bits() const = 0;
 
diff --git a/src/pubkey/pk_ops.h b/src/pubkey/pk_ops.h
index 7a5b1d94d..b15a8d8cd 100644
--- a/src/pubkey/pk_ops.h
+++ b/src/pubkey/pk_ops.h
@@ -51,19 +51,19 @@ class BOTAN_DLL Signature
    public:
       /**
       * Find out the number of message parts supported by this scheme.
-      * @return the number of message parts
+      * @return number of message parts
       */
       virtual u32bit message_parts() const { return 1; }
 
       /**
       * Find out the message part size supported by this scheme/key.
-      * @return the size of the message parts
+      * @return size of the message parts
       */
       virtual u32bit message_part_size() const { return 0; }
 
       /**
       * Get the maximum message size in bits supported by this public key.
-      * @return the maximum message in bits
+      * @return maximum message in bits
       */
       virtual u32bit max_input_bits() const = 0;
 
@@ -87,19 +87,19 @@ class BOTAN_DLL Verification
    public:
       /**
       * Get the maximum message size in bits supported by this public key.
-      * @return the maximum message in bits
+      * @return maximum message in bits
       */
       virtual u32bit max_input_bits() const = 0;
 
       /**
       * Find out the number of message parts supported by this scheme.
-      * @return the number of message parts
+      * @return number of message parts
       */
       virtual u32bit message_parts() const { return 1; }
 
       /**
       * Find out the message part size supported by this scheme/key.
-      * @return the size of the message parts
+      * @return size of the message parts
       */
       virtual u32bit message_part_size() const { return 0; }
 
diff --git a/src/pubkey/pkcs8.h b/src/pubkey/pkcs8.h
index 542d5bb2d..3da96d840 100644
--- a/src/pubkey/pkcs8.h
+++ b/src/pubkey/pkcs8.h
@@ -34,7 +34,7 @@ BOTAN_DLL SecureVector<byte> BER_encode(const Private_Key& key);
 /**
 * Get a string containing a PEM encoded private key.
 * @param key the key to encode
-* @return the encoded key
+* @return encoded key
 */
 BOTAN_DLL std::string PEM_encode(const Private_Key& key);
 
@@ -46,7 +46,7 @@ BOTAN_DLL std::string PEM_encode(const Private_Key& key);
 * @param pbe_algo the name of the desired password-based encryption
          algorithm; if empty ("") a reasonable (portable/secure)
          default will be chosen.
-* @return the encrypted key in binary BER form
+* @return encrypted key in binary BER form
 */
 BOTAN_DLL SecureVector<byte> BER_encode(const Private_Key& key,
                                         RandomNumberGenerator& rng,
@@ -62,7 +62,7 @@ BOTAN_DLL SecureVector<byte> BER_encode(const Private_Key& key,
 * @param pbe_algo the name of the desired password-based encryption
          algorithm; if empty ("") a reasonable (portable/secure)
          default will be chosen.
-* @return the encrypted key in PEM form
+* @return encrypted key in PEM form
 */
 BOTAN_DLL std::string PEM_encode(const Private_Key& key,
                                  RandomNumberGenerator& rng,
@@ -119,7 +119,7 @@ inline void encrypt_key(const Private_Key& key,
 * @param source the data source providing the encoded key
 * @param rng the rng to use
 * @param ui the user interface to be used for passphrase dialog
-* @return the loaded private key object
+* @return loaded private key object
 */
 BOTAN_DLL Private_Key* load_key(DataSource& source,
                                 RandomNumberGenerator& rng,
@@ -130,7 +130,7 @@ BOTAN_DLL Private_Key* load_key(DataSource& source,
 * @param rng the rng to use
 * @param pass the passphrase to decrypt the key. Provide an empty
 * string if the key is not encoded.
-* @return the loaded private key object
+* @return loaded private key object
 */
 BOTAN_DLL Private_Key* load_key(DataSource& source,
                                 RandomNumberGenerator& rng,
@@ -141,7 +141,7 @@ BOTAN_DLL Private_Key* load_key(DataSource& source,
 * @param filename the path to the file containing the encoded key
 * @param rng the rng to use
 * @param ui the user interface to be used for passphrase dialog
-* @return the loaded private key object
+* @return loaded private key object
 */
 BOTAN_DLL Private_Key* load_key(const std::string& filename,
                                 RandomNumberGenerator& rng,
@@ -152,7 +152,7 @@ BOTAN_DLL Private_Key* load_key(const std::string& filename,
 * @param rng the rng to use
 * @param pass the passphrase to decrypt the key. Provide an empty
 * string if the key is not encoded.
-* @return the loaded private key object
+* @return loaded private key object
 */
 BOTAN_DLL Private_Key* load_key(const std::string& filename,
                                 RandomNumberGenerator& rng,
@@ -162,7 +162,7 @@ BOTAN_DLL Private_Key* load_key(const std::string& filename,
 * Copy an existing encoded key object.
 * @param key the key to copy
 * @param rng the rng to use
-* @return the new copy of the key
+* @return new copy of the key
 */
 BOTAN_DLL Private_Key* copy_key(const Private_Key& key,
                                 RandomNumberGenerator& rng);
diff --git a/src/pubkey/pubkey.h b/src/pubkey/pubkey.h
index d034427e1..ff4355675 100644
--- a/src/pubkey/pubkey.h
+++ b/src/pubkey/pubkey.h
@@ -43,7 +43,7 @@ class BOTAN_DLL PK_Encryptor
       * @param in the message as a byte array
       * @param length the length of the above byte array
       * @param rng the random number source to use
-      * @return the encrypted message
+      * @return encrypted message
       */
       SecureVector<byte> encrypt(const byte in[], u32bit length,
                                  RandomNumberGenerator& rng) const
@@ -55,7 +55,7 @@ class BOTAN_DLL PK_Encryptor
       * Encrypt a message.
       * @param in the message
       * @param rng the random number source to use
-      * @return the encrypted message
+      * @return encrypted message
       */
       SecureVector<byte> encrypt(const MemoryRegion<byte>& in,
                                  RandomNumberGenerator& rng) const
@@ -65,7 +65,7 @@ class BOTAN_DLL PK_Encryptor
 
       /**
       * Return the maximum allowed message size in bytes.
-      * @return the maximum message size in bytes
+      * @return maximum message size in bytes
       */
       virtual u32bit maximum_input_size() const = 0;
 
@@ -89,7 +89,7 @@ class BOTAN_DLL PK_Decryptor
       * Decrypt a ciphertext.
       * @param in the ciphertext as a byte array
       * @param length the length of the above byte array
-      * @return the decrypted message
+      * @return decrypted message
       */
       SecureVector<byte> decrypt(const byte in[], u32bit length) const
          {
@@ -99,7 +99,7 @@ class BOTAN_DLL PK_Decryptor
       /**
       * Decrypt a ciphertext.
       * @param in the ciphertext
-      * @return the decrypted message
+      * @return decrypted message
       */
       SecureVector<byte> decrypt(const MemoryRegion<byte>& in) const
          {
@@ -128,7 +128,7 @@ class BOTAN_DLL PK_Signer
       * @param in the message to sign as a byte array
       * @param length the length of the above byte array
       * @param rng the rng to use
-      * @return the signature
+      * @return signature
       */
       SecureVector<byte> sign_message(const byte in[], u32bit length,
                                       RandomNumberGenerator& rng);
@@ -137,7 +137,7 @@ class BOTAN_DLL PK_Signer
       * Sign a message.
       * @param in the message to sign
       * @param rng the rng to use
-      * @return the signature
+      * @return signature
       */
       SecureVector<byte> sign_message(const MemoryRegion<byte>& in,
                                       RandomNumberGenerator& rng)
@@ -166,7 +166,7 @@ class BOTAN_DLL PK_Signer
       * Get the signature of the so far processed message (provided by the
       * calls to update()).
       * @param rng the rng to use
-      * @return the signature of the total message
+      * @return signature of the total message
       */
       SecureVector<byte> signature(RandomNumberGenerator& rng);
 
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/s2k/s2k.h b/src/s2k/s2k.h
index 5263dfd68..59e789a15 100644
--- a/src/s2k/s2k.h
+++ b/src/s2k/s2k.h
@@ -21,13 +21,13 @@ class BOTAN_DLL S2K
    public:
 
       /**
-      * @return a new instance of this same algorithm
+      * @return new instance of this same algorithm
       */
       virtual S2K* clone() const = 0;
 
       /**
       * Get the algorithm name.
-      * @return the name of this S2K algorithm
+      * @return name of this S2K algorithm
       */
       virtual std::string name() const = 0;
 
diff --git a/src/stream/stream_cipher.cpp b/src/stream/stream_cipher.cpp
new file mode 100644
index 000000000..9ae548a9e
--- /dev/null
+++ b/src/stream/stream_cipher.cpp
@@ -0,0 +1,24 @@
+/*
+* Stream Cipher
+* (C) 1999-2010 Jack Lloyd
+*
+* Distributed under the terms of the Botan license
+*/
+
+#include <botan/stream_cipher.h>
+
+namespace Botan {
+
+void StreamCipher::set_iv(const byte[], u32bit iv_len)
+   {
+   if(iv_len)
+      throw Invalid_Argument("The stream cipher " + name() +
+                             " does not support resyncronization");
+   }
+
+bool StreamCipher::valid_iv_length(u32bit iv_len) const
+   {
+   return (iv_len == 0);
+   }
+
+}
diff --git a/src/stream/stream_cipher.h b/src/stream/stream_cipher.h
index 4ce5cb1a4..edeb1aff5 100644
--- a/src/stream/stream_cipher.h
+++ b/src/stream/stream_cipher.h
@@ -39,19 +39,13 @@ class BOTAN_DLL StreamCipher : public SymmetricAlgorithm
       * @param iv the initialization vector
       * @param iv_len the length of the IV in bytes
       */
-      virtual void set_iv(const byte iv[], u32bit iv_len)
-         {
-         if(iv_len)
-            throw Invalid_Argument("The stream cipher " + name() +
-                                   " does not support resyncronization");
-         }
+      virtual void set_iv(const byte iv[], u32bit iv_len);
 
       /**
       * @param iv_len the length of the IV in bytes
       * @return if the length is valid for this algorithm
       */
-      virtual bool valid_iv_length(u32bit iv_len) const
-         { return (iv_len == 0); }
+      virtual bool valid_iv_length(u32bit iv_len) const;
 
       /**
       * Get a new object representing the same algorithm as *this
@@ -65,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/sym_algo/sym_algo.h b/src/sym_algo/sym_algo.h
index f1a4955ca..60180de90 100644
--- a/src/sym_algo/sym_algo.h
+++ b/src/sym_algo/sym_algo.h
@@ -38,7 +38,7 @@ class BOTAN_DLL SymmetricAlgorithm
 
       /**
       * The name of the algorithm.
-      * @return the name of the algorithm
+      * @return name of the algorithm
       */
       virtual std::string name() const = 0;
 
diff --git a/src/utils/buf_comp/buf_comp.h b/src/utils/buf_comp/buf_comp.h
index bbaa72919..e807e6abf 100644
--- a/src/utils/buf_comp/buf_comp.h
+++ b/src/utils/buf_comp/buf_comp.h
@@ -67,7 +67,7 @@ class BOTAN_DLL BufferedComputation
       /**
       * Complete the computation and retrieve the
       * final result.
-      * @return a SecureVector holding the result
+      * @return SecureVector holding the result
       */
       SecureVector<byte> final()
          {
@@ -113,12 +113,27 @@ class BOTAN_DLL BufferedComputation
          return final();
          }
 
+      /**
+      * @param out_len the output length of this computation
+      */
       BufferedComputation(u32bit out_len) : OUTPUT_LENGTH(out_len) {}
+
       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;
    };
 
 }
diff --git a/src/utils/time.h b/src/utils/time.h
index c1ab52021..fa1e379a7 100644
--- a/src/utils/time.h
+++ b/src/utils/time.h
@@ -25,13 +25,22 @@ struct BOTAN_DLL calendar_point
    byte minutes;
    byte seconds;
 
+   /**
+   * Initialize a calendar_point
+   * @param y the year
+   * @param mon the month
+   * @param d the day
+   * @param h the hour
+   * @param min the minute
+   * @param sec the second
+   */
    calendar_point(u32bit y, byte mon, byte d, byte h, byte min, byte sec) :
       year(y), month(mon), day(d), hour(h), minutes(min), seconds(sec) {}
    };
 
 /**
 * @param time_point a time point from the system clock
-* @returns calendar_point object representing this time point
+* @return calendar_point object representing this time point
 */
 BOTAN_DLL calendar_point calendar_value(u64bit time_point);
 
diff --git a/src/utils/version.h b/src/utils/version.h
index 9ed776ed7..13d0ac8bb 100644
--- a/src/utils/version.h
+++ b/src/utils/version.h
@@ -19,7 +19,7 @@ namespace Botan {
 
 /**
 * Get the version string identifying the version of Botan.
-* @return the version string
+* @return version string
 */
 BOTAN_DLL std::string version_string();
 
@@ -27,25 +27,25 @@ BOTAN_DLL std::string version_string();
 * Return the date this version of botan was released, in an
 * integer of the form YYYYMMDD. For instance a version released
 * on May 21, 2013 would return the integer 20130521
-* @return the release date
+* @return release date
 */
 BOTAN_DLL u32bit version_datestamp();
 
 /**
 * Get the major version number.
-* @return the major version number
+* @return major version number
 */
 BOTAN_DLL u32bit version_major();
 
 /**
 * Get the minor version number.
-* @return the minor version number
+* @return minor version number
 */
 BOTAN_DLL u32bit version_minor();
 
 /**
 * Get the patch number.
-* @return the patch number
+* @return patch number
 */
 BOTAN_DLL u32bit version_patch();