propagate from branch 'net.randombit.botan' (head 647eeb4f4cf8fa4cf487cdc463d48f09fe18658e)

            to branch 'net.randombit.botan.c++0x' (head 2539675db91883b11895ddc5244721e93c413321)

50 files changed, 923 insertions, 183 deletions

diff --git a/src/alloc/allocate.h b/src/alloc/allocate.h
index 819e2542c..5bce1f205 100644
--- a/src/alloc/allocate.h
+++ b/src/alloc/allocate.h
@@ -19,14 +19,42 @@ namespace Botan {
 class BOTAN_DLL Allocator
    {
    public:
-      static Allocator* get(bool);
+      /**
+      * Acquire a pointer to an allocator
+      * @param locking is true if the allocator should attempt to
+      *                secure the memory (eg for using to store keys)
+      * @return pointer to an allocator; ownership remains with library,
+      *                 so do not delete
+      */
+      static Allocator* get(bool locking);
 
-      virtual void* allocate(u32bit) = 0;
-      virtual void deallocate(void*, u32bit) = 0;
+      /**
+      * Allocate a block of memory
+      * @param n how many bytes to allocate
+      * @return pointer to n bytes of memory
+      */
+      virtual void* allocate(u32bit n) = 0;
 
+      /**
+      * Deallocate memory allocated with allocate()
+      * @param ptr the pointer returned by allocate()
+      * @param n the size of the block pointed to by ptr
+      */
+      virtual void deallocate(void* ptr, u32bit n) = 0;
+
+      /**
+      * @return name of this allocator type
+      */
       virtual std::string type() const = 0;
 
+      /**
+      * Initialize the allocator
+      */
       virtual void init() {}
+
+      /**
+      * Shutdown the allocator
+      */
       virtual void destroy() {}
 
       virtual ~Allocator() {}
diff --git a/src/alloc/secmem.h b/src/alloc/secmem.h
index 39b5549a9..bc5a2499d 100644
--- a/src/alloc/secmem.h
+++ b/src/alloc/secmem.h
@@ -195,6 +195,11 @@ class MemoryRegion
       ~MemoryRegion() { deallocate(buf, allocated); }
    protected:
       MemoryRegion() { buf = 0; alloc = 0; used = allocated = 0; }
+
+      /**
+      * Copy constructor
+      * @param other the other region to copy
+      */
       MemoryRegion(const MemoryRegion<T>& other)
          {
          buf = 0;
@@ -203,6 +208,10 @@ class MemoryRegion
          set(other.buf, other.used);
          }
 
+      /**
+      * @param locking should we use a locking allocator
+      * @param length the initial length to use
+      */
       void init(bool locking, u32bit length = 0)
          { alloc = Allocator::get(locking); resize(length); }
    private:
diff --git a/src/asn1/asn1_int.h b/src/asn1/asn1_int.h
index 3562f692b..cac46190f 100644
--- a/src/asn1/asn1_int.h
+++ b/src/asn1/asn1_int.h
@@ -56,8 +56,18 @@ enum ASN1_Tag {
 class BOTAN_DLL ASN1_Object
    {
    public:
-      virtual void encode_into(class DER_Encoder&) const = 0;
-      virtual void decode_from(class BER_Decoder&) = 0;
+      /**
+      * Encode whatever this object is into to
+      * @param to the DER_Encoder that will be written to
+      */
+      virtual void encode_into(class DER_Encoder& to) const = 0;
+
+      /**
+      * Decode whatever this object is from from
+      * @param from the BER_Decoder that will be read from
+      */
+      virtual void decode_from(class BER_Decoder& from) = 0;
+
       virtual ~ASN1_Object() {}
    };
 
@@ -80,9 +90,14 @@ class DataSource;
 
 namespace ASN1 {
 
-SecureVector<byte> put_in_sequence(const MemoryRegion<byte>&);
-std::string to_string(const BER_Object&);
-bool maybe_BER(DataSource&);
+SecureVector<byte> put_in_sequence(const MemoryRegion<byte>& val);
+std::string to_string(const BER_Object& obj);
+
+/**
+* Heuristics tests; is this object possibly BER?
+* @param src a data source that will be peeked at but not modified
+*/
+bool maybe_BER(DataSource& src);
 
 }
 
diff --git a/src/asn1/asn1_obj.h b/src/asn1/asn1_obj.h
index c0b74ea0e..3da376e2c 100644
--- a/src/asn1/asn1_obj.h
+++ b/src/asn1/asn1_obj.h
@@ -24,8 +24,8 @@ namespace Botan {
 class BOTAN_DLL Attribute : public ASN1_Object
    {
    public:
-      void encode_into(class DER_Encoder&) const;
-      void decode_from(class BER_Decoder&);
+      void encode_into(class DER_Encoder& to) const;
+      void decode_from(class BER_Decoder& from);
 
       OID oid;
       MemoryVector<byte> parameters;
diff --git a/src/block/idea/idea.h b/src/block/idea/idea.h
index e9ccf366d..aed3be3ea 100644
--- a/src/block/idea/idea.h
+++ b/src/block/idea/idea.h
@@ -26,10 +26,19 @@ class BOTAN_DLL IDEA : public BlockCipher
       BlockCipher* clone() const { return new IDEA; }
 
       IDEA() : BlockCipher(8, 16) {}
+   protected:
+      /**
+      * @return const reference to encryption subkeys
+      */
+      const SecureVector<u16bit, 52>& get_EK() const { return EK; }
+
+      /**
+      * @return const reference to decryption subkeys
+      */
+      const SecureVector<u16bit, 52>& get_DK() const { return DK; }
+
    private:
       void key_schedule(const byte[], u32bit);
-
-   protected: // for IDEA_SSE2
       SecureVector<u16bit, 52> EK, DK;
    };
 
diff --git a/src/block/idea_sse2/idea_sse2.cpp b/src/block/idea_sse2/idea_sse2.cpp
index 0fe35112d..0948bf46a 100644
--- a/src/block/idea_sse2/idea_sse2.cpp
+++ b/src/block/idea_sse2/idea_sse2.cpp
@@ -198,7 +198,7 @@ void IDEA_SSE2::encrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
    while(blocks >= 8)
       {
-      idea_op_8(in, out, this->EK);
+      idea_op_8(in, out, this->get_EK());
       in += 8 * BLOCK_SIZE;
       out += 8 * BLOCK_SIZE;
       blocks -= 8;
@@ -214,7 +214,7 @@ void IDEA_SSE2::decrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
    while(blocks >= 8)
       {
-      idea_op_8(in, out, this->DK);
+      idea_op_8(in, out, this->get_DK());
       in += 8 * BLOCK_SIZE;
       out += 8 * BLOCK_SIZE;
       blocks -= 8;
diff --git a/src/block/noekeon/noekeon.h b/src/block/noekeon/noekeon.h
index 018c1d1fd..2e524f8b8 100644
--- a/src/block/noekeon/noekeon.h
+++ b/src/block/noekeon/noekeon.h
@@ -26,15 +26,24 @@ class BOTAN_DLL Noekeon : public BlockCipher
       BlockCipher* clone() const { return new Noekeon; }
 
       Noekeon() : BlockCipher(16, 16) {}
-   private:
-      void key_schedule(const byte[], u32bit);
-   protected: // for access by SIMD subclass
-
+   protected:
       /**
       * The Noekeon round constants
       */
       static const byte RC[17];
 
+      /**
+      * @return const reference to encryption subkeys
+      */
+      const SecureVector<u32bit, 4>& get_EK() const { return EK; }
+
+      /**
+      * @return const reference to decryption subkeys
+      */
+      const SecureVector<u32bit, 4>& get_DK() const { return DK; }
+
+   private:
+      void key_schedule(const byte[], u32bit);
       SecureVector<u32bit, 4> EK, DK;
    };
 
diff --git a/src/block/noekeon_simd/noekeon_simd.cpp b/src/block/noekeon_simd/noekeon_simd.cpp
index f44104901..c36f269a4 100644
--- a/src/block/noekeon_simd/noekeon_simd.cpp
+++ b/src/block/noekeon_simd/noekeon_simd.cpp
@@ -55,6 +55,8 @@ namespace Botan {
 */
 void Noekeon_SIMD::encrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
+   const SecureVector<u32bit, 4>& EK = this->get_EK();
+
    SIMD_32 K0 = SIMD_32(EK[0]);
    SIMD_32 K1 = SIMD_32(EK[1]);
    SIMD_32 K2 = SIMD_32(EK[2]);
@@ -109,6 +111,8 @@ void Noekeon_SIMD::encrypt_n(const byte in[], byte out[], u32bit blocks) const
 */
 void Noekeon_SIMD::decrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
+   const SecureVector<u32bit, 4>& DK = this->get_DK();
+
    SIMD_32 K0 = SIMD_32(DK[0]);
    SIMD_32 K1 = SIMD_32(DK[1]);
    SIMD_32 K2 = SIMD_32(DK[2]);
diff --git a/src/block/serpent/serpent.h b/src/block/serpent/serpent.h
index 1c13d00f9..dc81d4178 100644
--- a/src/block/serpent/serpent.h
+++ b/src/block/serpent/serpent.h
@@ -26,8 +26,22 @@ class BOTAN_DLL Serpent : public BlockCipher
       BlockCipher* clone() const { return new Serpent; }
       Serpent() : BlockCipher(16, 16, 32, 8) {}
    protected:
+      /**
+      * For use by subclasses using SIMD, asm, etc
+      * @return const reference to the key schedule
+      */
+      const SecureVector<u32bit, 132>& get_round_keys() const
+         { return round_key; }
+
+      /**
+      * For use by subclasses that implement the key schedule
+      * @param ks is the new key schedule value to set
+      */
+      void set_round_keys(const u32bit ks[132])
+         { round_key.set(ks, 132); }
+
+   private:
       void key_schedule(const byte key[], u32bit length);
-
       SecureVector<u32bit, 132> round_key;
    };
 
diff --git a/src/block/serpent_ia32/serp_ia32.cpp b/src/block/serpent_ia32/serp_ia32.cpp
index ff454ab4c..ecdfec9b1 100644
--- a/src/block/serpent_ia32/serp_ia32.cpp
+++ b/src/block/serpent_ia32/serp_ia32.cpp
@@ -12,9 +12,32 @@ namespace Botan {
 
 extern "C" {
 
-void botan_serpent_ia32_encrypt(const byte[16], byte[16], const u32bit[132]);
-void botan_serpent_ia32_decrypt(const byte[16], byte[16], const u32bit[132]);
-void botan_serpent_ia32_key_schedule(u32bit[140]);
+/**
+* Entry point for Serpent encryption in x86 asm
+* @param in the input block
+* @param out the output block
+* @param ks the key schedule
+*/
+void botan_serpent_ia32_encrypt(const byte in[16],
+                                byte out[16],
+                                const u32bit ks[132]);
+
+/**
+* Entry point for Serpent decryption in x86 asm
+* @param in the input block
+* @param out the output block
+* @param ks the key schedule
+*/
+void botan_serpent_ia32_decrypt(const byte in[16],
+                                byte out[16],
+                                const u32bit ks[132]);
+
+/**
+* Entry point for Serpent key schedule in x86 asm
+* @param ks holds the initial working key (padded), and is set to the
+            final key schedule
+*/
+void botan_serpent_ia32_key_schedule(u32bit ks[140]);
 
 }
 
@@ -25,7 +48,7 @@ void Serpent_IA32::encrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
    for(u32bit i = 0; i != blocks; ++i)
       {
-      botan_serpent_ia32_encrypt(in, out, round_key);
+      botan_serpent_ia32_encrypt(in, out, this->get_round_keys());
       in += BLOCK_SIZE;
       out += BLOCK_SIZE;
       }
@@ -38,7 +61,7 @@ void Serpent_IA32::decrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
    for(u32bit i = 0; i != blocks; ++i)
       {
-      botan_serpent_ia32_decrypt(in, out, round_key);
+      botan_serpent_ia32_decrypt(in, out, this->get_round_keys());
       in += BLOCK_SIZE;
       out += BLOCK_SIZE;
       }
@@ -55,7 +78,7 @@ void Serpent_IA32::key_schedule(const byte key[], u32bit length)
    W[length / 4] |= u32bit(1) << ((length%4)*8);
 
    botan_serpent_ia32_key_schedule(W);
-   round_key.copy(W + 8, 132);
+   this->set_round_keys(W + 8);
    }
 
 }
diff --git a/src/block/serpent_simd/serp_simd.cpp b/src/block/serpent_simd/serp_simd.cpp
index 0a535c9a0..ba587e93d 100644
--- a/src/block/serpent_simd/serp_simd.cpp
+++ b/src/block/serpent_simd/serp_simd.cpp
@@ -182,7 +182,7 @@ void Serpent_SIMD::encrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
    while(blocks >= 4)
       {
-      serpent_encrypt_4(in, out, this->round_key);
+      serpent_encrypt_4(in, out, this->get_round_keys());
       in += 4 * BLOCK_SIZE;
       out += 4 * BLOCK_SIZE;
       blocks -= 4;
@@ -198,7 +198,7 @@ void Serpent_SIMD::decrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
    while(blocks >= 4)
       {
-      serpent_decrypt_4(in, out, this->round_key);
+      serpent_decrypt_4(in, out, this->get_round_keys());
       in += 4 * BLOCK_SIZE;
       out += 4 * BLOCK_SIZE;
       blocks -= 4;
diff --git a/src/block/xtea/xtea.h b/src/block/xtea/xtea.h
index b16cdf555..d15108939 100644
--- a/src/block/xtea/xtea.h
+++ b/src/block/xtea/xtea.h
@@ -27,6 +27,12 @@ class BOTAN_DLL XTEA : public BlockCipher
 
       XTEA() : BlockCipher(8, 16) {}
    protected:
+      /**
+      * @return const reference to the key schedule
+      */
+      const SecureVector<u32bit, 64>& get_EK() const { return EK; }
+
+   private:
       void key_schedule(const byte[], u32bit);
       SecureVector<u32bit, 64> EK;
    };
diff --git a/src/block/xtea_simd/xtea_simd.cpp b/src/block/xtea_simd/xtea_simd.cpp
index 264d4f949..44a4e81b6 100644
--- a/src/block/xtea_simd/xtea_simd.cpp
+++ b/src/block/xtea_simd/xtea_simd.cpp
@@ -96,7 +96,7 @@ void XTEA_SIMD::encrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
    while(blocks >= 8)
       {
-      xtea_encrypt_8(in, out, this->EK);
+      xtea_encrypt_8(in, out, this->get_EK());
       in += 8 * BLOCK_SIZE;
       out += 8 * BLOCK_SIZE;
       blocks -= 8;
@@ -112,7 +112,7 @@ void XTEA_SIMD::decrypt_n(const byte in[], byte out[], u32bit blocks) const
    {
    while(blocks >= 8)
       {
-      xtea_decrypt_8(in, out, this->EK);
+      xtea_decrypt_8(in, out, this->get_EK());
       in += 8 * BLOCK_SIZE;
       out += 8 * BLOCK_SIZE;
       blocks -= 8;
diff --git a/src/cert/x509/x509_obj.cpp b/src/cert/x509/x509_obj.cpp
index 1c8066c56..ffee74f12 100644
--- a/src/cert/x509/x509_obj.cpp
+++ b/src/cert/x509/x509_obj.cpp
@@ -88,20 +88,10 @@ void X509_Object::decode_info(DataSource& source)
 */
 void X509_Object::encode(Pipe& out, X509_Encoding encoding) const
    {
-   SecureVector<byte> der = DER_Encoder()
-      .start_cons(SEQUENCE)
-         .start_cons(SEQUENCE)
-            .raw_bytes(tbs_bits)
-         .end_cons()
-         .encode(sig_algo)
-         .encode(sig, BIT_STRING)
-      .end_cons()
-   .get_contents();
-
    if(encoding == PEM)
-      out.write(PEM_Code::encode(der, PEM_label_pref));
+      out.write(this->PEM_encode());
    else
-      out.write(der);
+      out.write(this->BER_encode());
    }
 
 /*
@@ -109,11 +99,15 @@ void X509_Object::encode(Pipe& out, X509_Encoding encoding) const
 */
 SecureVector<byte> X509_Object::BER_encode() const
    {
-   Pipe ber;
-   ber.start_msg();
-   encode(ber, RAW_BER);
-   ber.end_msg();
-   return ber.read_all();
+   return DER_Encoder()
+      .start_cons(SEQUENCE)
+         .start_cons(SEQUENCE)
+            .raw_bytes(tbs_bits)
+         .end_cons()
+         .encode(sig_algo)
+         .encode(sig, BIT_STRING)
+      .end_cons()
+   .get_contents();
    }
 
 /*
@@ -121,11 +115,7 @@ SecureVector<byte> X509_Object::BER_encode() const
 */
 std::string X509_Object::PEM_encode() const
    {
-   Pipe pem;
-   pem.start_msg();
-   encode(pem, PEM);
-   pem.end_msg();
-   return pem.read_all_as_string();
+   return PEM_Code::encode(BER_encode(), PEM_label_pref);
    }
 
 /*
diff --git a/src/cert/x509/x509_obj.h b/src/cert/x509/x509_obj.h
index 52b76d218..28ee95073 100644
--- a/src/cert/x509/x509_obj.h
+++ b/src/cert/x509/x509_obj.h
@@ -23,8 +23,21 @@ namespace Botan {
 class BOTAN_DLL X509_Object
    {
    public:
+
+      /**
+      * The underlying data that is to be or was signed
+      * @return data that is or was signed
+      */
       SecureVector<byte> tbs_data() const;
+
+      /**
+      * @return signature on tbs_data()
+      */
       SecureVector<byte> signature() const;
+
+      /**
+      * @return signature algorithm that was used to generate signature
+      */
       AlgorithmIdentifier signature_algorithm() const;
 
       /**
@@ -40,10 +53,29 @@ class BOTAN_DLL X509_Object
                                             const AlgorithmIdentifier& alg_id,
                                             const MemoryRegion<byte>& tbs);
 
-      bool check_signature(class Public_Key&) const;
+      /**
+      * Check the signature on this data
+      * @param key the public key purportedly used to sign this data
+      * @return true if the signature is valid, otherwise false
+      */
+      bool check_signature(class Public_Key& key) const;
 
-      void encode(Pipe&, X509_Encoding = PEM) const;
+      /**
+      * Encode this to a pipe
+      * @deprecated use BER_encode or PEM_encode instead
+      * @param out the pipe to write to
+      * @param encoding the encoding to use
+      */
+      void encode(Pipe& out, X509_Encoding encoding = PEM) const;
+
+      /**
+      * @return BER encoding of this
+      */
       SecureVector<byte> BER_encode() const;
+
+      /**
+      * @return PEM encoding of this
+      */
       std::string PEM_encode() const;
 
       X509_Object(DataSource&, const std::string&);
diff --git a/src/constructs/aont/package.h b/src/constructs/aont/package.h
index 211623347..34e0f35d5 100644
--- a/src/constructs/aont/package.h
+++ b/src/constructs/aont/package.h
@@ -1,6 +1,5 @@
 /*
 * Rivest's Package Tranform
-*
 * (C) 2009 Jack Lloyd
 *
 * Distributed under the terms of the Botan license
@@ -16,12 +15,12 @@ namespace Botan {
 
 /**
 * Rivest's Package Tranform
-* @arg rng the random number generator to use
-* @arg cipher the block cipher to use
-* @arg input the input data buffer
-* @arg input_len the length of the input data in bytes
-* @arg output the output data buffer (must be at least
-*      input_len + cipher->BLOCK_SIZE bytes long)
+* @param rng the random number generator to use
+* @param cipher the block cipher to use
+* @param input the input data buffer
+* @param input_len the length of the input data in bytes
+* @param output the output data buffer (must be at least
+*        input_len + cipher->BLOCK_SIZE bytes long)
 */
 void BOTAN_DLL aont_package(RandomNumberGenerator& rng,
                             BlockCipher* cipher,
@@ -30,12 +29,11 @@ void BOTAN_DLL aont_package(RandomNumberGenerator& rng,
 
 /**
 * Rivest's Package Tranform (Inversion)
-* @arg rng the random number generator to use
-* @arg cipher the block cipher to use
-* @arg input the input data buffer
-* @arg input_len the length of the input data in bytes
-* @arg output the output data buffer (must be at least
-*      input_len - cipher->BLOCK_SIZE bytes long)
+* @param cipher the block cipher to use
+* @param input the input data buffer
+* @param input_len the length of the input data in bytes
+* @param output the output data buffer (must be at least
+*        input_len - cipher->BLOCK_SIZE bytes long)
 */
 void BOTAN_DLL aont_unpackage(BlockCipher* cipher,
                               const byte input[], u32bit input_len,
diff --git a/src/constructs/fpe/fpe.cpp b/src/constructs/fpe/fpe.cpp
index a0b3274b5..4eaff0eb6 100644
--- a/src/constructs/fpe/fpe.cpp
+++ b/src/constructs/fpe/fpe.cpp
@@ -136,7 +136,7 @@ BigInt FPE_Encryptor::operator()(u32bit round_no, const BigInt& R)
 
 }
 
-/**
+/*
 * Generic Z_n FPE encryption, FE1 scheme
 */
 BigInt fpe_encrypt(const BigInt& n, const BigInt& X0,
@@ -164,7 +164,7 @@ BigInt fpe_encrypt(const BigInt& n, const BigInt& X0,
    return X;
    }
 
-/**
+/*
 * Generic Z_n FPE decryption, FD1 scheme
 */
 BigInt fpe_decrypt(const BigInt& n, const BigInt& X0,
diff --git a/src/constructs/fpe/fpe.h b/src/constructs/fpe/fpe.h
index 75f90247f..7a4a7861a 100644
--- a/src/constructs/fpe/fpe.h
+++ b/src/constructs/fpe/fpe.h
@@ -13,15 +13,23 @@
 
 namespace Botan {
 
-/*
+/**
 * Encrypt X from and onto the group Z_n using key and tweak
+* @param n the modulus
+* @param X the plaintext as a BigInt
+* @param key a random key
+* @param tweak will modify the ciphertext (think of as an IV)
 */
 BigInt BOTAN_DLL fpe_encrypt(const BigInt& n, const BigInt& X,
                              const SymmetricKey& key,
                              const MemoryRegion<byte>& tweak);
 
-/*
+/**
 * Decrypt X from and onto the group Z_n using key and tweak
+* @param n the modulus
+* @param X the ciphertext as a BigInt
+* @param key is the key used for encryption
+* @param tweak the same tweak used for encryption
 */
 BigInt BOTAN_DLL fpe_decrypt(const BigInt& n, const BigInt& X,
                              const SymmetricKey& key,
diff --git a/src/engine/def_engine/default_engine.h b/src/engine/def_engine/default_engine.h
index f7e6d9746..0d864e514 100644
--- a/src/engine/def_engine/default_engine.h
+++ b/src/engine/def_engine/default_engine.h
@@ -51,6 +51,13 @@ class Default_Engine : public Engine
                                           Algorithm_Factory&) const;
    };
 
+/**
+* Create a cipher mode filter object
+* @param block_cipher a block cipher object
+* @param direction are we encrypting or decrypting?
+* @param mode the name of the cipher mode to use
+* @param padding the mode padding to use (only used for ECB, CBC)
+*/
 Keyed_Filter* get_cipher_mode(const BlockCipher* block_cipher,
                               Cipher_Dir direction,
                               const std::string& mode,
diff --git a/src/entropy/proc_walk/info.txt b/src/entropy/proc_walk/info.txt
index fd65d8ffe..9039f0ad9 100644
--- a/src/entropy/proc_walk/info.txt
+++ b/src/entropy/proc_walk/info.txt
@@ -12,20 +12,17 @@ es_ftw.h
 aix
 cygwin
 darwin
-freebsd
 dragonfly
+freebsd
 hpux
 hurd
 irix
 linux
+netbsd
 openbsd
 qnx
 solaris
 tru64
-
-# Doesn't build on 2.0.2/x86 due to libc/libstdc++ header issues; no
-# big deal since it has /dev/*random
-#netbsd
 </os>
 
 <requires>
diff --git a/src/entropy/unix_procs/unix_cmd.h b/src/entropy/unix_procs/unix_cmd.h
index 3abca8f37..2dc55f6d7 100644
--- a/src/entropy/unix_procs/unix_cmd.h
+++ b/src/entropy/unix_procs/unix_cmd.h
@@ -27,8 +27,19 @@ struct Unix_Program
    Unix_Program(const char* n, u32bit p)
       { name_and_args = n; priority = p; working = true; }
 
+   /**
+   * The name and arguments for this command
+   */
    std::string name_and_args;
+
+   /**
+   * Priority: we scan from low to high
+   */
    u32bit priority;
+
+   /**
+   * Does this source seem to be working?
+   */
    bool working;
    };
 
diff --git a/src/filters/buf_filt.h b/src/filters/buf_filt.h
index 1ab402df7..3acf1f809 100644
--- a/src/filters/buf_filt.h
+++ b/src/filters/buf_filt.h
@@ -26,14 +26,27 @@ class BOTAN_DLL Buffered_Filter
 
       virtual ~Buffered_Filter() {}
    protected:
+      /**
+      * @return name of this filter object
+      */
       virtual std::string name() const = 0;
 
       virtual void buffered_block(const byte input[], u32bit length) = 0;
       virtual void buffered_final(const byte input[], u32bit length) = 0;
 
+      /**
+      * @return block size of inputs
+      */
       u32bit buffered_block_size() const { return main_block_mod; }
 
+      /**
+      * @return current position in the buffer
+      */
       u32bit current_position() const { return buffer_pos; }
+
+      /**
+      * Reset the buffer position
+      */
       void buffer_reset() { buffer_pos = 0; }
    private:
       u32bit main_block_mod, final_minimum;
diff --git a/src/filters/hex/hex.cpp b/src/filters/hex/hex.cpp
index 56576a8a0..430958ebd 100644
--- a/src/filters/hex/hex.cpp
+++ b/src/filters/hex/hex.cpp
@@ -13,6 +13,9 @@
 
 namespace Botan {
 
+/**
+* Size used for internal buffer in hex encoder/decoder
+*/
 const u32bit HEX_CODEC_BUFFER_SIZE = 256;
 
 /*
diff --git a/src/filters/hex/hex.h b/src/filters/hex/hex.h
index 035bf4ef9..b03b933bc 100644
--- a/src/filters/hex/hex.h
+++ b/src/filters/hex/hex.h
@@ -24,7 +24,7 @@ class BOTAN_DLL Hex_Encoder : public Filter
       enum Case { Uppercase, Lowercase };
 
       /**
-        Encode a single byte into two hex characters
+      * Encode a single byte into two hex characters
       */
       static void encode(byte in, byte out[2], Case the_case = Uppercase);
 
@@ -63,8 +63,19 @@ class BOTAN_DLL Hex_Encoder : public Filter
 class BOTAN_DLL Hex_Decoder : public Filter
    {
    public:
-      static byte decode(const byte[2]);
-      static bool is_valid(byte);
+      /**
+      * Decode a pair of hex chars to a byte
+      * @param in an array of two hex chars
+      * @return byte formed by decoding in
+      */
+      static byte decode(const byte in[2]);
+
+      /**
+      * Check if this character is a valid hex input
+      * @param c a single character
+      * @return true iff c is a valid hex char
+      */
+      static bool is_valid(byte c);
 
       void write(const byte[], u32bit);
       void end_msg();
diff --git a/src/libstate/lookup.h b/src/libstate/lookup.h
index 76e06b2de..debcee52b 100644
--- a/src/libstate/lookup.h
+++ b/src/libstate/lookup.h
@@ -19,12 +19,12 @@
 
 namespace Botan {
 
-/*
-* Retrieve an object from the lookup table
+/**
+* Retrieve an object prototype from the global factory
+* @param algo_spec an algorithm name
+* @return constant prototype object (use clone to create usable object),
+          library retains ownership
 */
-// NOTE: these functions return internally stored objects, library
-// retains ownership
-
 inline const BlockCipher*
 retrieve_block_cipher(const std::string& algo_spec)
    {
@@ -32,6 +32,12 @@ retrieve_block_cipher(const std::string& algo_spec)
    return af.prototype_block_cipher(algo_spec);
    }
 
+/**
+* Retrieve an object prototype from the global factory
+* @param algo_spec an algorithm name
+* @return constant prototype object (use clone to create usable object),
+          library retains ownership
+*/
 inline const StreamCipher*
 retrieve_stream_cipher(const std::string& algo_spec)
    {
@@ -39,6 +45,12 @@ retrieve_stream_cipher(const std::string& algo_spec)
    return af.prototype_stream_cipher(algo_spec);
    }
 
+/**
+* Retrieve an object prototype from the global factory
+* @param algo_spec an algorithm name
+* @return constant prototype object (use clone to create usable object),
+          library retains ownership
+*/
 inline const HashFunction*
 retrieve_hash(const std::string& algo_spec)
    {
@@ -46,6 +58,12 @@ retrieve_hash(const std::string& algo_spec)
    return af.prototype_hash_function(algo_spec);
    }
 
+/**
+* Retrieve an object prototype from the global factory
+* @param algo_spec an algorithm name
+* @return constant prototype object (use clone to create usable object),
+          library retains ownership
+*/
 inline const MessageAuthenticationCode*
 retrieve_mac(const std::string& algo_spec)
    {
diff --git a/src/math/numbertheory/curve_gfp.h b/src/math/numbertheory/curve_gfp.h
index 0a91fc52d..8a46a9735 100644
--- a/src/math/numbertheory/curve_gfp.h
+++ b/src/math/numbertheory/curve_gfp.h
@@ -52,14 +52,12 @@ class BOTAN_DLL CurveGFp
       // CurveGFp& operator=(const CurveGFp& other) = default;
 
       /**
-      * Get coefficient a
-      * @return coefficient a
+      * @return curve coefficient a
       */
       const BigInt& get_a() const { return a; }
 
       /**
-      * Get coefficient b
-      * @return coefficient b
+      * @return curve coefficient b
       */
       const BigInt& get_b() const { return b; }
 
@@ -94,11 +92,14 @@ class BOTAN_DLL CurveGFp
       */
       u32bit get_p_words() const { return p_words; }
 
+      /**
+      * @return modular reducer for p
+      */
       const Modular_Reducer& mod_p() const { return reducer_p; }
 
       /**
       * swaps the states of *this and other, does not throw
-      * @param other The curve to swap values with
+      * @param other curve to swap values with
       */
       void swap(CurveGFp& other)
          {
@@ -112,6 +113,11 @@ class BOTAN_DLL CurveGFp
          std::swap(p_dash, other.p_dash);
          }
 
+      /**
+      * Equality operator
+      * @param other curve to compare with
+      * @return true iff this is the same curve as other
+      */
       bool operator==(const CurveGFp& other) const
          {
          return (p == other.p && a == other.a && b == other.b);
@@ -130,6 +136,12 @@ class BOTAN_DLL CurveGFp
       Modular_Reducer reducer_p;
    };
 
+/**
+* Equality operator
+* @param lhs a curve
+* @param rhs a curve
+* @return true iff lhs is not the same as rhs
+*/
 inline bool operator!=(const CurveGFp& lhs, const CurveGFp& rhs)
    {
    return !(lhs == rhs);
diff --git a/src/math/numbertheory/numthry.h b/src/math/numbertheory/numthry.h
index 9a1005413..1ab64b038 100644
--- a/src/math/numbertheory/numthry.h
+++ b/src/math/numbertheory/numthry.h
@@ -15,13 +15,31 @@
 namespace Botan {
 
 /**
-* Fused Arithmetic Operation
+* Fused multiply-add
+* @param a an integer
+* @param b an integer
+* @param c an integer
+* @return (a*b)+c
 */
-BigInt BOTAN_DLL mul_add(const BigInt&, const BigInt&, const BigInt&);
-BigInt BOTAN_DLL sub_mul(const BigInt&, const BigInt&, const BigInt&);
+BigInt BOTAN_DLL mul_add(const BigInt& a,
+                         const BigInt& b,
+                         const BigInt& c);
 
-/*
-* Number Theory Functions
+/**
+* Fused subtract-multiply
+* @param a an integer
+* @param b an integer
+* @param c an integer
+* @return (a-b)*c
+*/
+BigInt BOTAN_DLL sub_mul(const BigInt& a,
+                         const BigInt& b,
+                         const BigInt& c);
+
+/**
+* Return the absolute value
+* @param n an integer
+* @return absolute value of n
 */
 inline BigInt abs(const BigInt& n) { return n.abs(); }
 
@@ -70,8 +88,14 @@ s32bit BOTAN_DLL jacobi(const BigInt& a,
 
 /**
 * Modular exponentation
+* @param b an integer base
+* @param x a positive exponent
+* @param m a positive modulus
+* @return (b^x) % m
 */
-BigInt BOTAN_DLL power_mod(const BigInt&, const BigInt&, const BigInt&);
+BigInt BOTAN_DLL power_mod(const BigInt& b,
+                           const BigInt& x,
+                           const BigInt& m);
 
 /**
 * Compute the square root of x modulo a prime using the
@@ -90,55 +114,114 @@ BigInt BOTAN_DLL ressol(const BigInt& x, const BigInt& p);
 */
 u32bit BOTAN_DLL low_zero_bits(const BigInt& x);
 
-/*
+/**
 * Primality Testing
+* @param n a positive integer to test for primality
+* @param rng a random number generator
+* @param level how hard to test
+* @return true if all primality tests passed, otherwise false
 */
 bool BOTAN_DLL primality_test(const BigInt& n,
                               RandomNumberGenerator& rng,
                               u32bit level = 1);
 
+/**
+* Quickly check for primality
+* @param n a positive integer to test for primality
+* @param rng a random number generator
+* @return true if all primality tests passed, otherwise false
+*/
 inline bool quick_check_prime(const BigInt& n, RandomNumberGenerator& rng)
    { return primality_test(n, rng, 0); }
 
+/**
+* Check for primality
+* @param n a positive integer to test for primality
+* @param rng a random number generator
+* @return true if all primality tests passed, otherwise false
+*/
 inline bool check_prime(const BigInt& n, RandomNumberGenerator& rng)
    { return primality_test(n, rng, 1); }
 
+/**
+* Verify primality - this function is slow but useful if you want to
+* ensure that a possibly malicious entity did not provide you with
+* something that 'looks like' a prime
+* @param n a positive integer to test for primality
+* @param rng a random number generator
+* @return true if all primality tests passed, otherwise false
+*/
 inline bool verify_prime(const BigInt& n, RandomNumberGenerator& rng)
    { return primality_test(n, rng, 2); }
 
-/*
-* Random Number Generation
+/**
+* Randomly generate a prime
+* @param rng a random number generator
+* @param bits how large the resulting prime should be in bits
+* @param coprime a positive integer the result should be coprime to
+* @param equiv a non-negative number that the result should be
+               equivalent to modulo equiv_mod
+* @param equiv_mod the modulus equiv should be checked against
+* @return random prime with the specified criteria
 */
 BigInt BOTAN_DLL random_prime(RandomNumberGenerator& rng,
                               u32bit bits, const BigInt& coprime = 1,
                               u32bit equiv = 1, u32bit equiv_mod = 2);
 
+/**
+* Return a 'safe' prime, of the form p=2*q+1 with q prime
+* @param rng a random number generator
+* @param bits is how long the resulting prime should be
+* @return prime randomly chosen from safe primes of length bits
+*/
 BigInt BOTAN_DLL random_safe_prime(RandomNumberGenerator& rng,
                                    u32bit bits);
 
-/*
-* DSA Parameter Generation
-*/
 class Algorithm_Factory;
 
+/**
+* Generate DSA parameters using the FIPS 186 kosherizer
+* @param rng a random number generator
+* @param af an algorithm factory
+* @param p_out where the prime p will be stored
+* @param q_out where the prime q will be stored
+* @param pbits how long p will be in bits
+* @param qbits how long q will be in bits
+* @return random seed used to generate this parameter set
+*/
 SecureVector<byte> BOTAN_DLL
 generate_dsa_primes(RandomNumberGenerator& rng,
                     Algorithm_Factory& af,
-                    BigInt& p, BigInt& q,
+                    BigInt& p_out, BigInt& q_out,
                     u32bit pbits, u32bit qbits);
 
+/**
+* Generate DSA parameters using the FIPS 186 kosherizer
+* @param rng a random number generator
+* @param af an algorithm factory
+* @param p_out where the prime p will be stored
+* @param q_out where the prime q will be stored
+* @param pbits how long p will be in bits
+* @param qbits how long q will be in bits
+* @param seed the seed used to generate the parameters
+* @return true if seed generated a valid DSA parameter set, otherwise
+          false. p_out and q_out are only valid if true was returned.
+*/
 bool BOTAN_DLL
 generate_dsa_primes(RandomNumberGenerator& rng,
                     Algorithm_Factory& af,
                     BigInt& p_out, BigInt& q_out,
-                    u32bit p_bits, u32bit q_bits,
+                    u32bit pbits, u32bit qbits,
                     const MemoryRegion<byte>& seed);
 
-/*
-* Prime Numbers
+/**
+* The size of the PRIMES[] array
 */
 const u32bit PRIME_TABLE_SIZE = 6541;
 
+/**
+* A const array of all primes less than 65535
+*/
 extern const u16bit BOTAN_DLL PRIMES[];
 
 }
diff --git a/src/pk_pad/eme.h b/src/pk_pad/eme.h
index 02b8208ef..1bc3ba3c9 100644
--- a/src/pk_pad/eme.h
+++ b/src/pk_pad/eme.h
@@ -19,22 +19,82 @@ namespace Botan {
 class BOTAN_DLL EME
    {
    public:
-      virtual u32bit maximum_input_size(u32bit) const = 0;
+      /**
+      * Return the maximum input size in bytes we can support
+      * @param keybits the size of the key in bits
+      * @return upper bound of input in bytes
+      */
+      virtual u32bit maximum_input_size(u32bit keybits) const = 0;
 
-      SecureVector<byte> encode(const byte[], u32bit, u32bit,
-                                RandomNumberGenerator&) const;
-      SecureVector<byte> encode(const MemoryRegion<byte>&, u32bit,
-                                RandomNumberGenerator&) const;
+      /**
+      * Encode an input
+      * @param in the plaintext
+      * @param in_length length of plaintext in bytes
+      * @param key_length length of the key in bits
+      * @param rng a random number generator
+      * @return encoded plaintext
+      */
+      SecureVector<byte> encode(const byte in[],
+                                u32bit in_length,
+                                u32bit key_length,
+                                RandomNumberGenerator& rng) const;
 
-      SecureVector<byte> decode(const byte[], u32bit, u32bit) const;
-      SecureVector<byte> decode(const MemoryRegion<byte>&, u32bit) const;
+      /**
+      * Encode an input
+      * @param in the plaintext
+      * @param key_length length of the key in bits
+      * @param rng a random number generator
+      * @return encoded plaintext
+      */
+      SecureVector<byte> encode(const MemoryRegion<byte>& in,
+                                u32bit key_length,
+                                RandomNumberGenerator& rng) const;
+
+      /**
+      * Decode an input
+      * @param in the encoded plaintext
+      * @param in_length length of encoded plaintext in bytes
+      * @param key_length length of the key in bits
+      * @return plaintext
+      */
+      SecureVector<byte> decode(const byte in[],
+                                u32bit in_length,
+                                u32bit key_length) const;
+
+      /**
+      * Decode an input
+      * @param in the encoded plaintext
+      * @param key_length length of the key in bits
+      * @return plaintext
+      */
+      SecureVector<byte> decode(const MemoryRegion<byte>& in,
+                                u32bit key_length) const;
 
       virtual ~EME() {}
    private:
-      virtual SecureVector<byte> pad(const byte[], u32bit, u32bit,
-                                     RandomNumberGenerator&) const = 0;
+      /**
+      * Encode an input
+      * @param in the plaintext
+      * @param in_length length of plaintext in bytes
+      * @param key_length length of the key in bits
+      * @param rng a random number generator
+      * @return encoded plaintext
+      */
+      virtual SecureVector<byte> pad(const byte in[],
+                                     u32bit in_length,
+                                     u32bit key_length,
+                                     RandomNumberGenerator& rng) const = 0;
 
-      virtual SecureVector<byte> unpad(const byte[], u32bit, u32bit) const = 0;
+      /**
+      * Decode an input
+      * @param in the encoded plaintext
+      * @param in_length length of encoded plaintext in bytes
+      * @param key_length length of the key in bits
+      * @return plaintext
+      */
+      virtual SecureVector<byte> unpad(const byte in[],
+                                       u32bit in_length,
+                                       u32bit key_length) const = 0;
    };
 
 }
diff --git a/src/pk_pad/eme1/eme1.h b/src/pk_pad/eme1/eme1.h
index d00eeeeb9..0ecdb279e 100644
--- a/src/pk_pad/eme1/eme1.h
+++ b/src/pk_pad/eme1/eme1.h
@@ -23,9 +23,8 @@ class BOTAN_DLL EME1 : public EME
       u32bit maximum_input_size(u32bit) const;
 
       /**
-       EME1 constructor. Hash will be deleted by ~EME1 (when mgf is deleted)
-
-       P is an optional label. Normally empty.
+      * @param hash object to use for hashing (takes ownership)
+      * @param P an optional label. Normally empty.
       */
       EME1(HashFunction* hash, const std::string& P = "");
 
diff --git a/src/pk_pad/emsa.h b/src/pk_pad/emsa.h
index 6d01beb7f..372eb836d 100644
--- a/src/pk_pad/emsa.h
+++ b/src/pk_pad/emsa.h
@@ -19,15 +19,39 @@ namespace Botan {
 class BOTAN_DLL EMSA
    {
    public:
-      virtual void update(const byte[], u32bit) = 0;
+      /**
+      * Add more data to the signature computation
+      * @param input some data
+      * @param length length of input in bytes
+      */
+      virtual void update(const byte input[], u32bit length) = 0;
+
+      /**
+      * @return raw hash
+      */
       virtual SecureVector<byte> raw_data() = 0;
 
-      virtual SecureVector<byte> encoding_of(const MemoryRegion<byte>&,
-                                             u32bit,
+      /**
+      * Return the encoding of a message
+      * @param msg the result of raw_data()
+      * @param output_bits the desired output bit size
+      * @param rng a random number generator
+      * @return encoded signature
+      */
+      virtual SecureVector<byte> encoding_of(const MemoryRegion<byte>& msg,
+                                             u32bit output_bits,
                                              RandomNumberGenerator& rng) = 0;
 
-      virtual bool verify(const MemoryRegion<byte>&, const MemoryRegion<byte>&,
-                          u32bit) = 0;
+      /**
+      * Verify the encoding
+      * @param coded the received (coded) message representative
+      * @param raw the computed (local, uncoded) message representative
+      * @param key_bits the size of the key in bits
+      * @return true if coded is a valid encoding of raw, otherwise false
+      */
+      virtual bool verify(const MemoryRegion<byte>& coded,
+                          const MemoryRegion<byte>& raw,
+                          u32bit key_bits) = 0;
       virtual ~EMSA() {}
    };
 
diff --git a/src/pk_pad/emsa1/emsa1.h b/src/pk_pad/emsa1/emsa1.h
index 28d856525..50fda5273 100644
--- a/src/pk_pad/emsa1/emsa1.h
+++ b/src/pk_pad/emsa1/emsa1.h
@@ -20,9 +20,15 @@ namespace Botan {
 class BOTAN_DLL EMSA1 : public EMSA
    {
    public:
+      /**
+      * @param h the hash object to use
+      */
       EMSA1(HashFunction* h) : hash(h) {}
       ~EMSA1() { delete hash; }
    protected:
+      /**
+      * @return const pointer to the underlying hash
+      */
       const HashFunction* hash_ptr() const { return hash; }
    private:
       void update(const byte[], u32bit);
diff --git a/src/pk_pad/emsa1_bsi/emsa1_bsi.h b/src/pk_pad/emsa1_bsi/emsa1_bsi.h
index ec86d40e2..a0a3515fb 100644
--- a/src/pk_pad/emsa1_bsi/emsa1_bsi.h
+++ b/src/pk_pad/emsa1_bsi/emsa1_bsi.h
@@ -21,6 +21,9 @@ implementation comes from InSiTo
 class BOTAN_DLL EMSA1_BSI : public EMSA1
    {
    public:
+      /**
+      * @param hash the hash object to use
+      */
       EMSA1_BSI(HashFunction* hash) : EMSA1(hash) {}
    private:
       SecureVector<byte> encoding_of(const MemoryRegion<byte>&, u32bit,
diff --git a/src/pk_pad/emsa2/emsa2.h b/src/pk_pad/emsa2/emsa2.h
index bda34fbd1..cfb3f9e12 100644
--- a/src/pk_pad/emsa2/emsa2.h
+++ b/src/pk_pad/emsa2/emsa2.h
@@ -20,6 +20,9 @@ namespace Botan {
 class BOTAN_DLL EMSA2 : public EMSA
    {
    public:
+      /**
+      * @param hash the hash object to use
+      */
       EMSA2(HashFunction* hash);
       ~EMSA2() { delete hash; }
    private:
diff --git a/src/pk_pad/emsa3/emsa3.cpp b/src/pk_pad/emsa3/emsa3.cpp
index dc905a464..82981d38c 100644
--- a/src/pk_pad/emsa3/emsa3.cpp
+++ b/src/pk_pad/emsa3/emsa3.cpp
@@ -12,7 +12,7 @@ namespace Botan {
 
 namespace {
 
-/**
+/*
 * EMSA3 Encode Operation
 */
 SecureVector<byte> emsa3_encoding(const MemoryRegion<byte>& msg,
@@ -37,7 +37,7 @@ SecureVector<byte> emsa3_encoding(const MemoryRegion<byte>& msg,
 
 }
 
-/**
+/*
 * EMSA3 Update Operation
 */
 void EMSA3::update(const byte input[], u32bit length)
@@ -45,7 +45,7 @@ void EMSA3::update(const byte input[], u32bit length)
    hash->update(input, length);
    }
 
-/**
+/*
 * Return the raw (unencoded) data
 */
 SecureVector<byte> EMSA3::raw_data()
@@ -53,7 +53,7 @@ SecureVector<byte> EMSA3::raw_data()
    return hash->final();
    }
 
-/**
+/*
 * EMSA3 Encode Operation
 */
 SecureVector<byte> EMSA3::encoding_of(const MemoryRegion<byte>& msg,
@@ -67,7 +67,7 @@ SecureVector<byte> EMSA3::encoding_of(const MemoryRegion<byte>& msg,
                          hash_id, hash_id.size());
    }
 
-/**
+/*
 * Default signature decoding
 */
 bool EMSA3::verify(const MemoryRegion<byte>& coded,
@@ -88,7 +88,7 @@ bool EMSA3::verify(const MemoryRegion<byte>& coded,
       }
    }
 
-/**
+/*
 * EMSA3 Constructor
 */
 EMSA3::EMSA3(HashFunction* hash_in) : hash(hash_in)
@@ -96,7 +96,7 @@ EMSA3::EMSA3(HashFunction* hash_in) : hash(hash_in)
    hash_id = pkcs_hash_id(hash->name());
    }
 
-/**
+/*
 * EMSA3 Destructor
 */
 EMSA3::~EMSA3()
@@ -104,7 +104,7 @@ EMSA3::~EMSA3()
    delete hash;
    }
 
-/**
+/*
 * EMSA3_Raw Update Operation
 */
 void EMSA3_Raw::update(const byte input[], u32bit length)
@@ -112,7 +112,7 @@ void EMSA3_Raw::update(const byte input[], u32bit length)
    message.append(input, length);
    }
 
-/**
+/*
 * Return the raw (unencoded) data
 */
 SecureVector<byte> EMSA3_Raw::raw_data()
@@ -122,7 +122,7 @@ SecureVector<byte> EMSA3_Raw::raw_data()
    return ret;
    }
 
-/**
+/*
 * EMSA3_Raw Encode Operation
 */
 SecureVector<byte> EMSA3_Raw::encoding_of(const MemoryRegion<byte>& msg,
@@ -132,7 +132,7 @@ SecureVector<byte> EMSA3_Raw::encoding_of(const MemoryRegion<byte>& msg,
    return emsa3_encoding(msg, output_bits, 0, 0);
    }
 
-/**
+/*
 * Default signature decoding
 */
 bool EMSA3_Raw::verify(const MemoryRegion<byte>& coded,
diff --git a/src/pk_pad/emsa3/emsa3.h b/src/pk_pad/emsa3/emsa3.h
index 1e080aab6..09c1e40cc 100644
--- a/src/pk_pad/emsa3/emsa3.h
+++ b/src/pk_pad/emsa3/emsa3.h
@@ -21,7 +21,10 @@ namespace Botan {
 class BOTAN_DLL EMSA3 : public EMSA
    {
    public:
-      EMSA3(HashFunction*);
+      /**
+      * @param hash the hash object to use
+      */
+      EMSA3(HashFunction* hash);
       ~EMSA3();
 
       void update(const byte[], u32bit);
diff --git a/src/pk_pad/emsa4/emsa4.h b/src/pk_pad/emsa4/emsa4.h
index 6315c424e..7dfc3892a 100644
--- a/src/pk_pad/emsa4/emsa4.h
+++ b/src/pk_pad/emsa4/emsa4.h
@@ -20,8 +20,16 @@ namespace Botan {
 class BOTAN_DLL EMSA4 : public EMSA
    {
    public:
-      EMSA4(HashFunction*);
-      EMSA4(HashFunction*, u32bit);
+      /**
+      * @param hash the hash object to use
+      */
+      EMSA4(HashFunction* hash);
+
+      /**
+      * @param hash the hash object to use
+      * @param salt_size the size of the salt to use in bytes
+      */
+      EMSA4(HashFunction* hash, u32bit salt_size);
 
       ~EMSA4() { delete hash; delete mgf; }
    private:
diff --git a/src/pk_pad/hash_id/hash_id.cpp b/src/pk_pad/hash_id/hash_id.cpp
index 203c27f14..173f02a6d 100644
--- a/src/pk_pad/hash_id/hash_id.cpp
+++ b/src/pk_pad/hash_id/hash_id.cpp
@@ -54,10 +54,8 @@ const byte TIGER_PKCS_ID[] = {
 
 }
 
-/**
-* @return HashID as specified by PKCS
-* For details see RFC 3447 section 9.2
-* http://tools.ietf.org/html/rfc3447#section-9.2
+/*
+* HashID as specified by PKCS
 */
 MemoryVector<byte> pkcs_hash_id(const std::string& name)
    {
@@ -94,8 +92,8 @@ MemoryVector<byte> pkcs_hash_id(const std::string& name)
    throw Invalid_Argument("No PKCS #1 identifier for " + name);
    }
 
-/**
-* @return HashID as specified by IEEE 1363/X9.31
+/*
+* HashID as specified by IEEE 1363/X9.31
 */
 byte ieee1363_hash_id(const std::string& name)
    {
diff --git a/src/pk_pad/hash_id/hash_id.h b/src/pk_pad/hash_id/hash_id.h
index 847d9106c..909cc6b19 100644
--- a/src/pk_pad/hash_id/hash_id.h
+++ b/src/pk_pad/hash_id/hash_id.h
@@ -13,11 +13,21 @@
 
 namespace Botan {
 
-/*
-* Return the values of various defined HashIDs
+/**
+* Return the PKCS #1 hash identifier
+* @see RFC 3447 section 9.2
+* @param hash_name the name of the hash function
+* @return byte sequence identifying the hash
+* @throw Invalid_Argument if the hash has no known PKCS #1 hash id
+*/
+BOTAN_DLL MemoryVector<byte> pkcs_hash_id(const std::string& hash_name);
+
+/**
+* Return the IEEE 1363 hash identifier
+* @param hash_name the name of the hash function
+* @return byte code identifying the hash, or 0 if not known
 */
-BOTAN_DLL MemoryVector<byte> pkcs_hash_id(const std::string&);
-BOTAN_DLL byte ieee1363_hash_id(const std::string&);
+BOTAN_DLL byte ieee1363_hash_id(const std::string& hash_name);
 
 }
 
diff --git a/src/pubkey/dl_algo/dl_algo.h b/src/pubkey/dl_algo/dl_algo.h
index 429bfb554..2cc632caa 100644
--- a/src/pubkey/dl_algo/dl_algo.h
+++ b/src/pubkey/dl_algo/dl_algo.h
@@ -67,7 +67,15 @@ class BOTAN_DLL DL_Scheme_PublicKey : public virtual Public_Key
 
    protected:
       DL_Scheme_PublicKey() {}
+
+      /**
+      * The DL public key
+      */
       BigInt y;
+
+      /**
+      * The DL group
+      */
       DL_Group group;
    };
 
@@ -94,6 +102,10 @@ class BOTAN_DLL DL_Scheme_PrivateKey : public virtual DL_Scheme_PublicKey,
 
    protected:
       DL_Scheme_PrivateKey() {}
+
+      /**
+      * The DL private key
+      */
       BigInt x;
    };
 
diff --git a/src/pubkey/pkcs8.h b/src/pubkey/pkcs8.h
index 3da96d840..376429d5b 100644
--- a/src/pubkey/pkcs8.h
+++ b/src/pubkey/pkcs8.h
@@ -22,6 +22,9 @@ struct BOTAN_DLL PKCS8_Exception : public Decoding_Error
       Decoding_Error("PKCS #8: " + error) {}
    };
 
+/**
+* This namespace contains functions for handling PKCS #8 private keys
+*/
 namespace PKCS8 {
 
 /**
diff --git a/src/selftest/selftest.h b/src/selftest/selftest.h
index df71e6f8e..091206579 100644
--- a/src/selftest/selftest.h
+++ b/src/selftest/selftest.h
@@ -15,13 +15,28 @@
 
 namespace Botan {
 
-/*
-* Self Tests
+/**
+* Run a set of self tests on some basic algorithms like AES and SHA-1
+* @param af an algorithm factory
+* @throws Self_Test_Error if a failure occured
 */
 BOTAN_DLL void confirm_startup_self_tests(Algorithm_Factory& af);
 
+/**
+* Run a set of self tests on some basic algorithms like AES and SHA-1
+* @param af an algorithm factory
+* @returns false if a failure occured, otherwise true
+*/
 BOTAN_DLL bool passes_self_tests(Algorithm_Factory& af);
 
+/**
+* Run a set of algorithm KATs (known answer tests)
+* @param algo_name the algorithm we are testing
+* @param vars a set of input variables for this test, all
+         hex encoded. Keys used: "input", "output", "key", and "iv"
+* @param af an algorithm factory
+* @returns map from provider name to test result for that provider
+*/
 BOTAN_DLL std::map<std::string, bool>
 algorithm_kat(const SCAN_Name& algo_name,
               const std::map<std::string, std::string>& vars,
diff --git a/src/sym_algo/symkey.h b/src/sym_algo/symkey.h
index 450dab306..07b588329 100644
--- a/src/sym_algo/symkey.h
+++ b/src/sym_algo/symkey.h
@@ -140,10 +140,15 @@ BOTAN_DLL OctetString operator+(const OctetString& x,
 BOTAN_DLL OctetString operator^(const OctetString& x,
                                 const OctetString& y);
 
-/*
-* Alternate Names
+
+/**
+* Alternate name for octet string showing intent to use as a key
 */
 typedef OctetString SymmetricKey;
+
+/**
+* Alternate name for octet string showing intent to use as an IV
+*/
 typedef OctetString InitializationVector;
 
 }
diff --git a/src/utils/bit_ops.h b/src/utils/bit_ops.h
index c02ec536f..36bac9f73 100644
--- a/src/utils/bit_ops.h
+++ b/src/utils/bit_ops.h
@@ -12,9 +12,10 @@
 
 namespace Botan {
 
-/*
-* Return true iff arg is 2**n for some n > 0
-* T should be an unsigned integer type
+/**
+* Power of 2 test. T should be an unsigned integer type
+* @param arg an integer value
+* @return true iff arg is 2^n for some n > 0
 */
 template<typename T>
 inline bool power_of_2(T arg)
@@ -22,9 +23,11 @@ inline bool power_of_2(T arg)
    return ((arg != 0 && arg != 1) && ((arg & (arg-1)) == 0));
    }
 
-/*
+/**
 * Return the index of the highest set bit
 * T is an unsigned integer type
+* @param n an integer value
+* @return index of the highest set bit in n
 */
 template<typename T>
 inline u32bit high_bit(T n)
@@ -35,8 +38,11 @@ inline u32bit high_bit(T n)
    return 0;
    }
 
-/*
+/**
 * Return the index of the lowest set bit
+* T is an unsigned integer type
+* @param n an integer value
+* @return index of the lowest set bit in n
 */
 template<typename T>
 inline u32bit low_bit(T n)
@@ -47,8 +53,10 @@ inline u32bit low_bit(T n)
    return 0;
    }
 
-/*
+/**
 * Return the number of significant bytes in n
+* @param n an integer value
+* @return number of significant bytes in n
 */
 template<typename T>
 inline u32bit significant_bytes(T n)
@@ -59,8 +67,10 @@ inline u32bit significant_bytes(T n)
    return 0;
    }
 
-/*
-* Return the Hamming weight of n
+/**
+* Compute Hamming weights
+* @param n an integer value
+* @return number of bits in n set to 1
 */
 template<typename T>
 inline u32bit hamming_weight(T n)
@@ -74,8 +84,10 @@ inline u32bit hamming_weight(T n)
    return weight;
    }
 
-/*
+/**
 * Count the trailing zero bits in n
+* @param n an integer value
+* @return maximum x st 2^x divides n
 */
 template<typename T>
 inline u32bit ctz(T n)
diff --git a/src/utils/cpuid.h b/src/utils/cpuid.h
index a41e932fb..dbac89455 100644
--- a/src/utils/cpuid.h
+++ b/src/utils/cpuid.h
@@ -18,15 +18,6 @@ namespace Botan {
 class BOTAN_DLL CPUID
    {
    public:
-      enum CPUID_bits {
-         CPUID_RDTSC_BIT = 4,
-         CPUID_SSE2_BIT = 26,
-         CPUID_SSSE3_BIT = 41,
-         CPUID_SSE41_BIT = 51,
-         CPUID_SSE42_BIT = 52,
-         CPUID_INTEL_AES_BIT = 57
-      };
-
       /**
       * Return a best guess of the cache line size
       */
@@ -73,6 +64,15 @@ class BOTAN_DLL CPUID
       */
       static bool has_altivec();
    private:
+      enum CPUID_bits {
+         CPUID_RDTSC_BIT = 4,
+         CPUID_SSE2_BIT = 26,
+         CPUID_SSSE3_BIT = 41,
+         CPUID_SSE41_BIT = 51,
+         CPUID_SSE42_BIT = 52,
+         CPUID_INTEL_AES_BIT = 57
+      };
+
       static u64bit x86_processor_flags();
    };
 
diff --git a/src/utils/get_byte.h b/src/utils/get_byte.h
index fce87af83..7eedbd783 100644
--- a/src/utils/get_byte.h
+++ b/src/utils/get_byte.h
@@ -12,8 +12,11 @@
 
 namespace Botan {
 
-/*
-* Byte Extraction Function
+/**
+* Byte extraction
+* @param byte_num which byte to extract, 0 == highest byte
+* @param input the value to extract from
+* @return byte byte_num of input
 */
 template<typename T> inline byte get_byte(u32bit byte_num, T input)
    {
diff --git a/src/utils/loadstor.h b/src/utils/loadstor.h
index ffd27540d..e812fca4e 100644
--- a/src/utils/loadstor.h
+++ b/src/utils/loadstor.h
@@ -38,14 +38,25 @@
 
 namespace Botan {
 
-/*
-* Byte to Word Conversions
+/**
+* Make a u16bit from two bytes
+* @param i0 the first byte
+* @param i1 the second byte
+* @return i0 || i1
 */
 inline u16bit make_u16bit(byte i0, byte i1)
    {
    return ((static_cast<u16bit>(i0) << 8) | i1);
    }
 
+/**
+* Make a u32bit from four bytes
+* @param i0 the first byte
+* @param i1 the second byte
+* @param i2 the third byte
+* @param i3 the fourth byte
+* @return i0 || i1 || i2 || i3
+*/
 inline u32bit make_u32bit(byte i0, byte i1, byte i2, byte i3)
    {
    return ((static_cast<u32bit>(i0) << 24) |
@@ -54,6 +65,18 @@ inline u32bit make_u32bit(byte i0, byte i1, byte i2, byte i3)
            (static_cast<u32bit>(i3)));
    }
 
+/**
+* Make a u32bit from eight bytes
+* @param i0 the first byte
+* @param i1 the second byte
+* @param i2 the third byte
+* @param i3 the fourth byte
+* @param i4 the fifth byte
+* @param i5 the sixth byte
+* @param i6 the seventh byte
+* @param i7 the eighth byte
+* @return i0 || i1 || i2 || i3 || i4 || i5 || i6 || i7
+*/
 inline u64bit make_u64bit(byte i0, byte i1, byte i2, byte i3,
                           byte i4, byte i5, byte i6, byte i7)
     {
@@ -67,8 +90,11 @@ inline u64bit make_u64bit(byte i0, byte i1, byte i2, byte i3,
            (static_cast<u64bit>(i7)));
     }
 
-/*
-* Endian-Specific Word Loading Operations
+/**
+* Load a big-endian word
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th T of in, as a big-endian value
 */
 template<typename T>
 inline T load_be(const byte in[], u32bit off)
@@ -80,6 +106,12 @@ inline T load_be(const byte in[], u32bit off)
    return out;
    }
 
+/**
+* Load a little-endian word
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th T of in, as a litte-endian value
+*/
 template<typename T>
 inline T load_le(const byte in[], u32bit off)
    {
@@ -90,6 +122,12 @@ inline T load_le(const byte in[], u32bit off)
    return out;
    }
 
+/**
+* Load a big-endian u16bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u16bit of in, as a big-endian value
+*/
 template<>
 inline u16bit load_be<u16bit>(const byte in[], u32bit off)
    {
@@ -101,6 +139,12 @@ inline u16bit load_be<u16bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a little-endian u16bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u16bit of in, as a little-endian value
+*/
 template<>
 inline u16bit load_le<u16bit>(const byte in[], u32bit off)
    {
@@ -112,6 +156,12 @@ inline u16bit load_le<u16bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a big-endian u32bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u32bit of in, as a big-endian value
+*/
 template<>
 inline u32bit load_be<u32bit>(const byte in[], u32bit off)
    {
@@ -123,6 +173,12 @@ inline u32bit load_be<u32bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a little-endian u32bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u32bit of in, as a little-endian value
+*/
 template<>
 inline u32bit load_le<u32bit>(const byte in[], u32bit off)
    {
@@ -134,6 +190,12 @@ inline u32bit load_le<u32bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a big-endian u64bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u64bit of in, as a big-endian value
+*/
 template<>
 inline u64bit load_be<u64bit>(const byte in[], u32bit off)
    {
@@ -146,6 +208,12 @@ inline u64bit load_be<u64bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load a little-endian u64bit
+* @param in a pointer to some bytes
+* @param off an offset into the array
+* @return off'th u64bit of in, as a little-endian value
+*/
 template<>
 inline u64bit load_le<u64bit>(const byte in[], u32bit off)
    {
@@ -158,6 +226,12 @@ inline u64bit load_le<u64bit>(const byte in[], u32bit off)
 #endif
    }
 
+/**
+* Load two little-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+*/
 template<typename T>
 inline void load_le(const byte in[], T& x0, T& x1)
    {
@@ -165,6 +239,14 @@ inline void load_le(const byte in[], T& x0, T& x1)
    x1 = load_le<T>(in, 1);
    }
 
+/**
+* Load four little-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+* @param x2 where the third word will be written
+* @param x3 where the fourth word will be written
+*/
 template<typename T>
 inline void load_le(const byte in[],
                     T& x0, T& x1, T& x2, T& x3)
@@ -175,6 +257,18 @@ inline void load_le(const byte in[],
    x3 = load_le<T>(in, 3);
    }
 
+/**
+* Load eight little-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+* @param x2 where the third word will be written
+* @param x3 where the fourth word will be written
+* @param x4 where the fifth word will be written
+* @param x5 where the sixth word will be written
+* @param x6 where the seventh word will be written
+* @param x7 where the eighth word will be written
+*/
 template<typename T>
 inline void load_le(const byte in[],
                     T& x0, T& x1, T& x2, T& x3,
@@ -190,6 +284,12 @@ inline void load_le(const byte in[],
    x7 = load_le<T>(in, 7);
    }
 
+/**
+* Load a variable number of little-endian words
+* @param out the output array of words
+* @param in the input array of bytes
+* @param count how many words are in in
+*/
 template<typename T>
 inline void load_le(T out[],
                     const byte in[],
@@ -215,6 +315,12 @@ inline void load_le(T out[],
 #endif
    }
 
+/**
+* Load two big-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+*/
 template<typename T>
 inline void load_be(const byte in[], T& x0, T& x1)
    {
@@ -222,6 +328,14 @@ inline void load_be(const byte in[], T& x0, T& x1)
    x1 = load_be<T>(in, 1);
    }
 
+/**
+* Load four big-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+* @param x2 where the third word will be written
+* @param x3 where the fourth word will be written
+*/
 template<typename T>
 inline void load_be(const byte in[],
                     T& x0, T& x1, T& x2, T& x3)
@@ -232,6 +346,18 @@ inline void load_be(const byte in[],
    x3 = load_be<T>(in, 3);
    }
 
+/**
+* Load eight big-endian words
+* @param in a pointer to some bytes
+* @param x0 where the first word will be written
+* @param x1 where the second word will be written
+* @param x2 where the third word will be written
+* @param x3 where the fourth word will be written
+* @param x4 where the fifth word will be written
+* @param x5 where the sixth word will be written
+* @param x6 where the seventh word will be written
+* @param x7 where the eighth word will be written
+*/
 template<typename T>
 inline void load_be(const byte in[],
                     T& x0, T& x1, T& x2, T& x3,
@@ -247,6 +373,12 @@ inline void load_be(const byte in[],
    x7 = load_be<T>(in, 7);
    }
 
+/**
+* Load a variable number of big-endian words
+* @param out the output array of words
+* @param in the input array of bytes
+* @param count how many words are in in
+*/
 template<typename T>
 inline void load_be(T out[],
                     const byte in[],
@@ -272,8 +404,10 @@ inline void load_be(T out[],
 #endif
    }
 
-/*
-* Endian-Specific Word Storing Operations
+/**
+* Store a big-endian u16bit
+* @param in the input u16bit
+* @param out the byte array to write to
 */
 inline void store_be(u16bit in, byte out[2])
    {
@@ -285,6 +419,11 @@ inline void store_be(u16bit in, byte out[2])
 #endif
    }
 
+/**
+* Store a little-endian u16bit
+* @param in the input u16bit
+* @param out the byte array to write to
+*/
 inline void store_le(u16bit in, byte out[2])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -295,6 +434,11 @@ inline void store_le(u16bit in, byte out[2])
 #endif
    }
 
+/**
+* Store a big-endian u32bit
+* @param in the input u32bit
+* @param out the byte array to write to
+*/
 inline void store_be(u32bit in, byte out[4])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -307,6 +451,11 @@ inline void store_be(u32bit in, byte out[4])
 #endif
    }
 
+/**
+* Store a little-endian u32bit
+* @param in the input u32bit
+* @param out the byte array to write to
+*/
 inline void store_le(u32bit in, byte out[4])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -319,6 +468,11 @@ inline void store_le(u32bit in, byte out[4])
 #endif
    }
 
+/**
+* Store a big-endian u64bit
+* @param in the input u64bit
+* @param out the byte array to write to
+*/
 inline void store_be(u64bit in, byte out[8])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -335,6 +489,11 @@ inline void store_be(u64bit in, byte out[8])
 #endif
    }
 
+/**
+* Store a little-endian u64bit
+* @param in the input u64bit
+* @param out the byte array to write to
+*/
 inline void store_le(u64bit in, byte out[8])
    {
 #if BOTAN_TARGET_UNALIGNED_MEMORY_ACCESS_OK
@@ -351,6 +510,12 @@ inline void store_le(u64bit in, byte out[8])
 #endif
    }
 
+/**
+* Store two little-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+*/
 template<typename T>
 inline void store_le(byte out[], T x0, T x1)
    {
@@ -358,6 +523,12 @@ inline void store_le(byte out[], T x0, T x1)
    store_le(x1, out + (1 * sizeof(T)));
    }
 
+/**
+* Store two big-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+*/
 template<typename T>
 inline void store_be(byte out[], T x0, T x1)
    {
@@ -365,6 +536,14 @@ inline void store_be(byte out[], T x0, T x1)
    store_be(x1, out + (1 * sizeof(T)));
    }
 
+/**
+* Store four little-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+* @param x2 the third word
+* @param x3 the fourth word
+*/
 template<typename T>
 inline void store_le(byte out[], T x0, T x1, T x2, T x3)
    {
@@ -374,6 +553,14 @@ inline void store_le(byte out[], T x0, T x1, T x2, T x3)
    store_le(x3, out + (3 * sizeof(T)));
    }
 
+/**
+* Store four big-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+* @param x2 the third word
+* @param x3 the fourth word
+*/
 template<typename T>
 inline void store_be(byte out[], T x0, T x1, T x2, T x3)
    {
@@ -383,6 +570,18 @@ inline void store_be(byte out[], T x0, T x1, T x2, T x3)
    store_be(x3, out + (3 * sizeof(T)));
    }
 
+/**
+* Store eight little-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+* @param x2 the third word
+* @param x3 the fourth word
+* @param x4 the fifth word
+* @param x5 the sixth word
+* @param x6 the seventh word
+* @param x7 the eighth word
+*/
 template<typename T>
 inline void store_le(byte out[], T x0, T x1, T x2, T x3,
                                  T x4, T x5, T x6, T x7)
@@ -397,6 +596,18 @@ inline void store_le(byte out[], T x0, T x1, T x2, T x3,
    store_le(x7, out + (7 * sizeof(T)));
    }
 
+/**
+* Store eight big-endian words
+* @param out the output byte array
+* @param x0 the first word
+* @param x1 the second word
+* @param x2 the third word
+* @param x3 the fourth word
+* @param x4 the fifth word
+* @param x5 the sixth word
+* @param x6 the seventh word
+* @param x7 the eighth word
+*/
 template<typename T>
 inline void store_be(byte out[], T x0, T x1, T x2, T x3,
                                  T x4, T x5, T x6, T x7)
diff --git a/src/utils/mem_ops.h b/src/utils/mem_ops.h
index 0fcf34ba8..503be90b3 100644
--- a/src/utils/mem_ops.h
+++ b/src/utils/mem_ops.h
@@ -13,18 +13,47 @@
 
 namespace Botan {
 
-/*
-* Memory Manipulation Functions
+/**
+* Copy memory
+* @param out the destination array
+* @param in the source array
+* @param n the number of elements of in/out
 */
 template<typename T> inline void copy_mem(T* out, const T* in, u32bit n)
-   { std::memmove(out, in, sizeof(T)*n); }
+   {
+   std::memmove(out, in, sizeof(T)*n);
+   }
 
+/**
+* Zeroize memory
+* @param ptr a pointer to an array
+* @param n the number of Ts pointed to by ptr
+*/
 template<typename T> inline void clear_mem(T* ptr, u32bit n)
-   { if(n) std::memset(ptr, 0, sizeof(T)*n); }
+   {
+   if(n) // avoid glibc warning if n == 0
+      std::memset(ptr, 0, sizeof(T)*n);
+   }
 
-template<typename T> inline void set_mem(T* ptr, u32bit n, byte val)
-   { std::memset(ptr, val, sizeof(T)*n); }
+/**
+* Set memory to a fixed value
+* @param ptr a pointer to an array
+* @param n the number of Ts pointed to by ptr
+* @param val the value to set each byte to
+*/
+template<typename T>
+inline void set_mem(T* ptr, u32bit n, byte val)
+   {
+   std::memset(ptr, val, sizeof(T)*n);
+   }
 
+/**
+* Memory comparison, input insensitive
+* @param p1 a pointer to an array
+* @param p2 a pointer to another array
+* @param n the number of Ts in p1 and p2
+* @return true iff p1[i] == p2[i] forall i in [0...n)
+*/
 template<typename T> inline bool same_mem(const T* p1, const T* p2, u32bit n)
    {
    bool is_same = true;
diff --git a/src/utils/time.cpp b/src/utils/time.cpp
index 4fea41c52..d5b74828b 100644
--- a/src/utils/time.cpp
+++ b/src/utils/time.cpp
@@ -35,7 +35,7 @@ namespace Botan {
 
 namespace {
 
-/**
+/*
 * Combine a two time values into a single one
 */
 u64bit combine_timers(u32bit seconds, u32bit parts, u32bit parts_hz)
diff --git a/src/utils/time.h b/src/utils/time.h
index c7a7e0e1a..516efba3e 100644
--- a/src/utils/time.h
+++ b/src/utils/time.h
@@ -18,11 +18,24 @@ namespace Botan {
 */
 struct BOTAN_DLL calendar_point
    {
+   /** The year */
    u32bit year;
+
+   /** The month, 1 through 12 for Jan to Dec */
    byte month;
+
+   /** The day of the month, 1 through 31 (or 28 or 30 based on month */
    byte day;
+
+   /** Hour in 24-hour form, 0 to 23 */
    byte hour;
+
+   /** Minutes in the hour, 0 to 60 */
    byte minutes;
+
+   /** Seconds in the minute, 0 to 60, but might be slightly
+       larger to deal with leap seconds on some systems
+   */
    byte seconds;
 
    /**
diff --git a/src/utils/types.h b/src/utils/types.h
index 304628d02..58fdb5ff8 100644
--- a/src/utils/types.h
+++ b/src/utils/types.h
@@ -10,14 +10,34 @@
 
 #include <botan/build.h>
 
+/**
+* The primary namespace for the botan library
+*/
 namespace Botan {
 
+/**
+* Typedef representing an unsigned 8-bit quantity
+*/
 typedef unsigned char byte;
+
+/**
+* Typedef representing an unsigned 16-bit quantity
+*/
 typedef unsigned short u16bit;
+
+/**
+* Typedef representing an unsigned 32-bit quantity
+*/
 typedef unsigned int u32bit;
 
+/**
+* Typedef representing a signed 32-bit quantity
+*/
 typedef signed int s32bit;
 
+/**
+* Typedef representing an unsigned 64-bit quantity
+*/
 #if defined(_MSC_VER) || defined(__BORLANDC__)
    typedef unsigned __int64 u64bit;
 #elif defined(__KCC)
@@ -28,6 +48,9 @@ typedef signed int s32bit;
    typedef unsigned long long u64bit;
 #endif
 
+/**
+* A default buffer size; typically a memory page
+*/
 static const u32bit DEFAULT_BUFFERSIZE = BOTAN_DEFAULT_BUFFER_SIZE;
 
 }