propagate from branch 'net.randombit.botan' (head 294e2082ce9231d6165276e2f2a4153a0116aca3)

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

329 files changed, 2576 insertions, 1521 deletions

diff --git a/src/algo_factory/algo_cache.h b/src/algo_factory/algo_cache.h
index bafea45e9..45c64628d 100644
--- a/src/algo_factory/algo_cache.h
+++ b/src/algo_factory/algo_cache.h
@@ -30,11 +30,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,
@@ -42,15 +50,23 @@ 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);
 
+      /**
+      * Constructor
+      * @param m a mutex to serialize internal access
+      */
       ~Algorithm_Cache();
    private:
       typename std::map<std::string, std::map<std::string, T*> >::const_iterator
@@ -62,7 +78,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
 */
@@ -84,7 +100,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>
@@ -132,7 +148,7 @@ const T* Algorithm_Cache<T>::get(const std::string& algo_spec,
    return prototype;
    }
 
-/**
+/*
 * Add an implementation to the cache
 */
 template<typename T>
@@ -155,7 +171,7 @@ void Algorithm_Cache<T>::add(T* algo,
       }
    }
 
-/**
+/*
 * Find the providers of this algo (if any)
 */
 template<typename T> std::vector<std::string>
@@ -180,7 +196,7 @@ Algorithm_Cache<T>::providers_of(const std::string& algo_name)
    return providers;
    }
 
-/**
+/*
 * Set the preferred provider for an algorithm
 */
 template<typename T>
@@ -192,7 +208,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/algo_factory/algo_factory.cpp b/src/algo_factory/algo_factory.cpp
index 5f3e752bd..2de4461cd 100644
--- a/src/algo_factory/algo_factory.cpp
+++ b/src/algo_factory/algo_factory.cpp
@@ -22,7 +22,7 @@ namespace Botan {
 
 namespace {
 
-/**
+/*
 * Template functions for the factory prototype/search algorithm
 */
 template<typename T>
@@ -84,7 +84,7 @@ const T* factory_prototype(const std::string& algo_spec,
 
 }
 
-/**
+/*
 * Setup caches
 */
 Algorithm_Factory::Algorithm_Factory()
@@ -95,7 +95,7 @@ Algorithm_Factory::Algorithm_Factory()
    mac_cache = new Algorithm_Cache<MessageAuthenticationCode>();
    }
 
-/**
+/*
 * Delete all engines
 */
 Algorithm_Factory::~Algorithm_Factory()
@@ -114,7 +114,7 @@ void Algorithm_Factory::add_engine(Engine* engine)
    engines.push_back(engine);
    }
 
-/**
+/*
 * Set the preferred provider for an algorithm
 */
 void Algorithm_Factory::set_preferred_provider(const std::string& algo_spec,
@@ -130,7 +130,7 @@ void Algorithm_Factory::set_preferred_provider(const std::string& algo_spec,
       mac_cache->set_preferred_provider(algo_spec, provider);
    }
 
-/**
+/*
 * Get an engine out of the list
 */
 Engine* Algorithm_Factory::get_engine_n(u32bit n) const
@@ -140,7 +140,7 @@ Engine* Algorithm_Factory::get_engine_n(u32bit n) const
    return engines[n];
    }
 
-/**
+/*
 * Return the possible providers of a request
 * Note: assumes you don't have different types by the same name
 */
@@ -164,7 +164,7 @@ Algorithm_Factory::providers_of(const std::string& algo_spec)
       return std::vector<std::string>();
    }
 
-/**
+/*
 * Return the prototypical block cipher corresponding to this request
 */
 const BlockCipher*
@@ -175,7 +175,7 @@ Algorithm_Factory::prototype_block_cipher(const std::string& algo_spec,
                                           *this, block_cipher_cache);
    }
 
-/**
+/*
 * Return the prototypical stream cipher corresponding to this request
 */
 const StreamCipher*
@@ -186,7 +186,7 @@ Algorithm_Factory::prototype_stream_cipher(const std::string& algo_spec,
                                           *this, stream_cipher_cache);
    }
 
-/**
+/*
 * Return the prototypical object corresponding to this request (if found)
 */
 const HashFunction*
@@ -197,7 +197,7 @@ Algorithm_Factory::prototype_hash_function(const std::string& algo_spec,
                                           *this, hash_cache);
    }
 
-/**
+/*
 * Return the prototypical object corresponding to this request
 */
 const MessageAuthenticationCode*
@@ -209,7 +209,7 @@ Algorithm_Factory::prototype_mac(const std::string& algo_spec,
                                                        *this, mac_cache);
    }
 
-/**
+/*
 * Return a new block cipher corresponding to this request
 */
 BlockCipher*
@@ -221,7 +221,7 @@ Algorithm_Factory::make_block_cipher(const std::string& algo_spec,
    throw Algorithm_Not_Found(algo_spec);
    }
 
-/**
+/*
 * Return a new stream cipher corresponding to this request
 */
 StreamCipher*
@@ -233,7 +233,7 @@ Algorithm_Factory::make_stream_cipher(const std::string& algo_spec,
    throw Algorithm_Not_Found(algo_spec);
    }
 
-/**
+/*
 * Return a new object corresponding to this request
 */
 HashFunction*
@@ -245,7 +245,7 @@ Algorithm_Factory::make_hash_function(const std::string& algo_spec,
    throw Algorithm_Not_Found(algo_spec);
    }
 
-/**
+/*
 * Return a new object corresponding to this request
 */
 MessageAuthenticationCode*
@@ -257,7 +257,7 @@ Algorithm_Factory::make_mac(const std::string& algo_spec,
    throw Algorithm_Not_Found(algo_spec);
    }
 
-/**
+/*
 * Add a new block cipher
 */
 void Algorithm_Factory::add_block_cipher(BlockCipher* block_cipher,
@@ -266,7 +266,7 @@ void Algorithm_Factory::add_block_cipher(BlockCipher* block_cipher,
    block_cipher_cache->add(block_cipher, block_cipher->name(), provider);
    }
 
-/**
+/*
 * Add a new stream cipher
 */
 void Algorithm_Factory::add_stream_cipher(StreamCipher* stream_cipher,
@@ -275,7 +275,7 @@ void Algorithm_Factory::add_stream_cipher(StreamCipher* stream_cipher,
    stream_cipher_cache->add(stream_cipher, stream_cipher->name(), provider);
    }
 
-/**
+/*
 * Add a new hash
 */
 void Algorithm_Factory::add_hash_function(HashFunction* hash,
@@ -284,7 +284,7 @@ void Algorithm_Factory::add_hash_function(HashFunction* hash,
    hash_cache->add(hash, hash->name(), provider);
    }
 
-/**
+/*
 * Add a new mac
 */
 void Algorithm_Factory::add_mac(MessageAuthenticationCode* mac,
diff --git a/src/algo_factory/algo_factory.h b/src/algo_factory/algo_factory.h
index 92653ab66..881194f0c 100644
--- a/src/algo_factory/algo_factory.h
+++ b/src/algo_factory/algo_factory.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Algorithm Factory
 * (C) 2008 Jack Lloyd
 *
@@ -154,13 +154,21 @@ class BOTAN_DLL Algorithm_Factory
       void add_mac(MessageAuthenticationCode* algo,
                    const std::string& provider);
 
-      /*
-      * Deprecated
+      /**
+      * An iterator for the engines in this factory
+      * @deprecated
       */
       class BOTAN_DLL Engine_Iterator
          {
          public:
+            /**
+            * @return next engine in the sequence
+            */
             class Engine* next() { return af.get_engine_n(n++); }
+
+            /**
+            * @param a an algorithm factory
+            */
             Engine_Iterator(const Algorithm_Factory& a) : af(a) { n = 0; }
          private:
             const Algorithm_Factory& af;
diff --git a/src/algo_factory/prov_weight.cpp b/src/algo_factory/prov_weight.cpp
index 17284d024..0ca588aa9 100644
--- a/src/algo_factory/prov_weight.cpp
+++ b/src/algo_factory/prov_weight.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Default provider weights for Algorithm_Cache
 * (C) 2008 Jack Lloyd
 *
diff --git a/src/alloc/alloc_mmap/mmap_mem.cpp b/src/alloc/alloc_mmap/mmap_mem.cpp
index 4a7019ae7..a2059a6ea 100644
--- a/src/alloc/alloc_mmap/mmap_mem.cpp
+++ b/src/alloc/alloc_mmap/mmap_mem.cpp
@@ -6,6 +6,7 @@
 */
 
 #include <botan/internal/mmap_mem.h>
+#include <vector>
 #include <cstring>
 
 #include <sys/types.h>
@@ -44,29 +45,38 @@ void* MemoryMapping_Allocator::alloc_block(u32bit n)
       {
       public:
          int get_fd() const { return fd; }
-         const std::string path() const { return filepath; }
 
          TemporaryFile(const std::string& base)
             {
-            const std::string path = base + "XXXXXX";
+            const std::string mkstemp_template = base + "XXXXXX";
 
-            filepath = new char[path.length() + 1];
-            std::strcpy(filepath, path.c_str());
+            std::vector<char> filepath(mkstemp_template.begin(),
+                                       mkstemp_template.end());
+            filepath.push_back(0); // add terminating NULL
 
             mode_t old_umask = ::umask(077);
-            fd = ::mkstemp(filepath);
+            fd = ::mkstemp(&filepath[0]);
             ::umask(old_umask);
+
+            if(fd == -1)
+               throw MemoryMapping_Failed("Temporary file allocation failed");
+
+            if(::unlink(&filepath[0]) != 0)
+               throw MemoryMapping_Failed("Could not unlink temporary file");
             }
 
          ~TemporaryFile()
             {
-            delete[] filepath;
+            /*
+            * We can safely close here, because post-mmap the file
+            * will continue to exist until the mmap is unmapped from
+            * our address space upon deallocation.
+            */
             if(fd != -1 && ::close(fd) == -1)
                throw MemoryMapping_Failed("Could not close file");
             }
       private:
          int fd;
-         char* filepath;
       };
 
    TemporaryFile file("/tmp/botan_");
@@ -74,9 +84,6 @@ void* MemoryMapping_Allocator::alloc_block(u32bit n)
    if(file.get_fd() == -1)
       throw MemoryMapping_Failed("Could not create file");
 
-   if(::unlink(file.path().c_str()))
-      throw MemoryMapping_Failed("Could not unlink file '" + file.path() + "'");
-
    if(::lseek(file.get_fd(), n-1, SEEK_SET) < 0)
       throw MemoryMapping_Failed("Could not seek file");
 
diff --git a/src/alloc/alloc_mmap/mmap_mem.h b/src/alloc/alloc_mmap/mmap_mem.h
index 14caf5db1..890658ebc 100644
--- a/src/alloc/alloc_mmap/mmap_mem.h
+++ b/src/alloc/alloc_mmap/mmap_mem.h
@@ -12,8 +12,11 @@
 
 namespace Botan {
 
-/*
-* Memory Mapping Allocator
+/**
+* Allocator that uses memory maps backed by disk. We zeroize the map
+* upon deallocation. If swap occurs, the VM will swap to the shared
+* file backing rather than to a swap device, which means we know where
+* it is and can zap it later.
 */
 class MemoryMapping_Allocator : public Pooling_Allocator
    {
diff --git a/src/alloc/allocate.h b/src/alloc/allocate.h
index 180f2c021..819e2542c 100644
--- a/src/alloc/allocate.h
+++ b/src/alloc/allocate.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Allocator Interface
 */
 class BOTAN_DLL Allocator
diff --git a/src/alloc/mem_pool/mem_pool.h b/src/alloc/mem_pool/mem_pool.h
index f0a564965..f2b57a73b 100644
--- a/src/alloc/mem_pool/mem_pool.h
+++ b/src/alloc/mem_pool/mem_pool.h
@@ -16,7 +16,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Pooling Allocator
 */
 class Pooling_Allocator : public Allocator
diff --git a/src/alloc/secmem.h b/src/alloc/secmem.h
index b3b3fa973..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()); }
 
@@ -97,8 +97,8 @@ class MemoryRegion
       /**
       * Copy the contents of another buffer into this buffer.
       * The former contents of *this are discarded.
-      * @param in the buffer to copy the contents from.
-      * @return a reference to *this
+      * @param other the buffer to copy the contents from.
+      * @return reference to *this
       */
       MemoryRegion<T>& operator=(const MemoryRegion<T>& other)
          { if(this != &other) set(other); return (*this); }
@@ -156,7 +156,7 @@ class MemoryRegion
 
       /**
       * Append data to the end of this buffer.
-      * @param data the buffer containing the data to append
+      * @param other the buffer containing the data to append
       */
       void append(const MemoryRegion<T>& other)
          { append(other.begin(), other.size()); }
@@ -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/alloc/system_alloc/defalloc.h b/src/alloc/system_alloc/defalloc.h
index 436549540..54583d7b1 100644
--- a/src/alloc/system_alloc/defalloc.h
+++ b/src/alloc/system_alloc/defalloc.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Malloc Allocator
+/**
+* Allocator using malloc
 */
 class Malloc_Allocator : public Allocator
    {
@@ -24,8 +24,8 @@ class Malloc_Allocator : public Allocator
       std::string type() const { return "malloc"; }
    };
 
-/*
-* Locking Allocator
+/**
+* Allocator using malloc plus locking
 */
 class Locking_Allocator : public Pooling_Allocator
    {
diff --git a/src/asn1/alg_id.h b/src/asn1/alg_id.h
index 4a1ad2f30..417a71b30 100644
--- a/src/asn1/alg_id.h
+++ b/src/asn1/alg_id.h
@@ -14,7 +14,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Algorithm Identifier
 */
 class BOTAN_DLL AlgorithmIdentifier : public ASN1_Object
diff --git a/src/asn1/asn1_int.h b/src/asn1/asn1_int.h
index e6fb09398..3562f692b 100644
--- a/src/asn1/asn1_int.h
+++ b/src/asn1/asn1_int.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * ASN.1 Type and Class Tags
 */
 enum ASN1_Tag {
@@ -50,7 +50,7 @@ enum ASN1_Tag {
    DIRECTORY_STRING = 0xFF01
 };
 
-/*
+/**
 * Basic ASN.1 Object Interface
 */
 class BOTAN_DLL ASN1_Object
@@ -61,7 +61,7 @@ class BOTAN_DLL ASN1_Object
       virtual ~ASN1_Object() {}
    };
 
-/*
+/**
 * BER Encoded Object
 */
 class BOTAN_DLL BER_Object
@@ -86,7 +86,7 @@ bool maybe_BER(DataSource&);
 
 }
 
-/*
+/**
 * General BER Decoding Error Exception
 */
 struct BOTAN_DLL BER_Decoding_Error : public Decoding_Error
@@ -94,7 +94,7 @@ struct BOTAN_DLL BER_Decoding_Error : public Decoding_Error
    BER_Decoding_Error(const std::string&);
    };
 
-/*
+/**
 * Exception For Incorrect BER Taggings
 */
 struct BOTAN_DLL BER_Bad_Tag : public BER_Decoding_Error
diff --git a/src/asn1/asn1_obj.h b/src/asn1/asn1_obj.h
index a640f712b..c0b74ea0e 100644
--- a/src/asn1/asn1_obj.h
+++ b/src/asn1/asn1_obj.h
@@ -18,7 +18,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Attribute
 */
 class BOTAN_DLL Attribute : public ASN1_Object
@@ -35,7 +35,7 @@ class BOTAN_DLL Attribute : public ASN1_Object
       Attribute(const std::string&, const MemoryRegion<byte>&);
    };
 
-/*
+/**
 * X.509 Time
 */
 class BOTAN_DLL X509_Time : public ASN1_Object
@@ -62,7 +62,7 @@ class BOTAN_DLL X509_Time : public ASN1_Object
       ASN1_Tag tag;
    };
 
-/*
+/**
 * Simple String
 */
 class BOTAN_DLL ASN1_String : public ASN1_Object
@@ -83,7 +83,7 @@ class BOTAN_DLL ASN1_String : public ASN1_Object
       ASN1_Tag tag;
    };
 
-/*
+/**
 * Distinguished Name
 */
 class BOTAN_DLL X509_DN : public ASN1_Object
@@ -113,7 +113,7 @@ class BOTAN_DLL X509_DN : public ASN1_Object
       MemoryVector<byte> dn_bits;
    };
 
-/*
+/**
 * Alternative Name
 */
 class BOTAN_DLL AlternativeName : public ASN1_Object
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/asn1/ber_dec.h b/src/asn1/ber_dec.h
index 359b2e7dd..296d11037 100644
--- a/src/asn1/ber_dec.h
+++ b/src/asn1/ber_dec.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * BER Decoding Object
 */
 class BOTAN_DLL BER_Decoder
diff --git a/src/asn1/der_enc.h b/src/asn1/der_enc.h
index 23b5297e5..ae10b4bc8 100644
--- a/src/asn1/der_enc.h
+++ b/src/asn1/der_enc.h
@@ -13,7 +13,10 @@
 
 namespace Botan {
 
-/*
+class BigInt;
+class ASN1_Object;
+
+/**
 * General DER Encoding Object
 */
 class BOTAN_DLL DER_Encoder
@@ -33,13 +36,13 @@ class BOTAN_DLL DER_Encoder
       DER_Encoder& encode_null();
       DER_Encoder& encode(bool);
       DER_Encoder& encode(u32bit);
-      DER_Encoder& encode(const class BigInt&);
+      DER_Encoder& encode(const BigInt&);
       DER_Encoder& encode(const MemoryRegion<byte>&, ASN1_Tag);
       DER_Encoder& encode(const byte[], u32bit, ASN1_Tag);
 
       DER_Encoder& encode(bool, ASN1_Tag, ASN1_Tag = CONTEXT_SPECIFIC);
       DER_Encoder& encode(u32bit, ASN1_Tag, ASN1_Tag = CONTEXT_SPECIFIC);
-      DER_Encoder& encode(const class BigInt&, ASN1_Tag,
+      DER_Encoder& encode(const BigInt&, ASN1_Tag,
                           ASN1_Tag = CONTEXT_SPECIFIC);
       DER_Encoder& encode(const MemoryRegion<byte>&, ASN1_Tag,
                           ASN1_Tag, ASN1_Tag = CONTEXT_SPECIFIC);
@@ -62,7 +65,7 @@ class BOTAN_DLL DER_Encoder
          return (*this);
          }
 
-      DER_Encoder& encode(const class ASN1_Object&);
+      DER_Encoder& encode(const ASN1_Object&);
       DER_Encoder& encode_if(bool, DER_Encoder&);
 
       DER_Encoder& add_object(ASN1_Tag, ASN1_Tag, const byte[], u32bit);
diff --git a/src/benchmark/benchmark.cpp b/src/benchmark/benchmark.cpp
index 2b0ed7cb6..3ae4e1d5e 100644
--- a/src/benchmark/benchmark.cpp
+++ b/src/benchmark/benchmark.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Runtime benchmarking
 * (C) 2008-2009 Jack Lloyd
 *
diff --git a/src/benchmark/benchmark.h b/src/benchmark/benchmark.h
index baabc14ca..dfd2d7050 100644
--- a/src/benchmark/benchmark.h
+++ b/src/benchmark/benchmark.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Runtime benchmarking
 * (C) 2008-2009 Jack Lloyd
 *
diff --git a/src/block/aes/aes.cpp b/src/block/aes/aes.cpp
index df2674f34..bf9a4198b 100644
--- a/src/block/aes/aes.cpp
+++ b/src/block/aes/aes.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * AES
 * (C) 1999-2009 Jack Lloyd
 *
@@ -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 45026f732..8770bdb35 100644
--- a/src/block/aes/aes.h
+++ b/src/block/aes/aes.h
@@ -1,4 +1,4 @@
-/**
+/*
 * AES
 * (C) 1999-2009 Jack Lloyd
 *
@@ -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 3d3683d7d..211bb3b47 100644
--- a/src/block/aes_intel/aes_intel.cpp
+++ b/src/block/aes_intel/aes_intel.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * AES using Intel's AES-NI instructions
 * (C) 2009 Jack Lloyd
 *
@@ -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/aes_intel/aes_intel.h b/src/block/aes_intel/aes_intel.h
index a3ebf153b..592fb7faa 100644
--- a/src/block/aes_intel/aes_intel.h
+++ b/src/block/aes_intel/aes_intel.h
@@ -1,4 +1,4 @@
-/**
+/*
 * AES using Intel's AES-NI instructions
 * (C) 2009 Jack Lloyd
 *
@@ -18,7 +18,7 @@ namespace Botan {
 class BOTAN_DLL AES_128_Intel : public BlockCipher
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
@@ -40,7 +40,7 @@ class BOTAN_DLL AES_128_Intel : public BlockCipher
 class BOTAN_DLL AES_192_Intel : public BlockCipher
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
@@ -62,7 +62,7 @@ class BOTAN_DLL AES_192_Intel : public BlockCipher
 class BOTAN_DLL AES_256_Intel : public BlockCipher
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
diff --git a/src/block/aes_intel/info.txt b/src/block/aes_intel/info.txt
index 6e67a6ed9..8bf0f07ee 100644
--- a/src/block/aes_intel/info.txt
+++ b/src/block/aes_intel/info.txt
@@ -2,7 +2,7 @@ define AES_INTEL
 
 load_on auto
 
-need_isa aes_ni
+need_isa aes-ni
 
 <requires>
 aes_isa_eng
diff --git a/src/block/block_cipher.h b/src/block/block_cipher.h
index 2d9198c58..c1b58996e 100644
--- a/src/block/block_cipher.h
+++ b/src/block/block_cipher.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Block Cipher Base Class
 * (C) 1999-2009 Jack Lloyd
 *
@@ -19,14 +19,38 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
    {
    public:
       /**
+      * BlockCipher constructor
+      * @param block_size the size of blocks this cipher processes
+      * @param key_min the minimum key size
+      * @param key_max the maximum key size
+      * @param key_mod the modulo restriction on the key size
+      */
+      BlockCipher(u32bit block_size,
+                  u32bit key_min,
+                  u32bit key_max = 0,
+                  u32bit key_mod = 1) :
+         SymmetricAlgorithm(key_min, key_max, key_mod),
+         BLOCK_SIZE(block_size) {}
+
+      virtual ~BlockCipher() {}
+
+      /**
       * The block size of this algorithm.
       */
       const u32bit BLOCK_SIZE;
 
       /**
-      * @return the preferred parallelism of this cipher
+      * @return native parallelism of this cipher in blocks
       */
-      virtual u32bit parallelism() const { return 4; }
+      virtual u32bit parallelism() const { return 1; }
+
+      /**
+      * @return prefererred parallelism of this cipher in bytes
+      */
+      u32bit parallel_bytes() const
+         {
+         return parallelism() * BLOCK_SIZE * BOTAN_BLOCK_CIPHER_PAR_MULT;
+         }
 
       /**
       * Encrypt a block.
@@ -50,7 +74,7 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
 
       /**
       * Encrypt a block.
-      * @param in The plaintext block to be encrypted as a byte array.
+      * @param block the plaintext block to be encrypted
       * Must be of length BLOCK_SIZE. Will hold the result when the function
       * has finished.
       */
@@ -58,7 +82,7 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
 
       /**
       * Decrypt a block.
-      * @param in The ciphertext block to be decrypted as a byte array.
+      * @param block the ciphertext block to be decrypted
       * Must be of length BLOCK_SIZE. Will hold the result when the function
       * has finished.
       */
@@ -91,15 +115,6 @@ class BOTAN_DLL BlockCipher : public SymmetricAlgorithm
       * Zeroize internal state
       */
       virtual void clear() = 0;
-
-      BlockCipher(u32bit block_size,
-                  u32bit key_min,
-                  u32bit key_max = 0,
-                  u32bit key_mod = 1) :
-         SymmetricAlgorithm(key_min, key_max, key_mod),
-         BLOCK_SIZE(block_size) {}
-
-      virtual ~BlockCipher() {}
    };
 
 }
diff --git a/src/block/blowfish/blowfish.h b/src/block/blowfish/blowfish.h
index 2306f0e37..a178ec488 100644
--- a/src/block/blowfish/blowfish.h
+++ b/src/block/blowfish/blowfish.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Blowfish
 */
 class BOTAN_DLL Blowfish : public BlockCipher
diff --git a/src/block/cascade/cascade.h b/src/block/cascade/cascade.h
index 98c64fb3e..abd9b015d 100644
--- a/src/block/cascade/cascade.h
+++ b/src/block/cascade/cascade.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Block Cipher Cascade
 */
 class BOTAN_DLL Cascade_Cipher : public BlockCipher
@@ -25,6 +25,11 @@ class BOTAN_DLL Cascade_Cipher : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const;
 
+      /**
+      * Create a cascade of two block ciphers
+      * @param cipher1 the first cipher
+      * @param cipher2 the second cipher
+      */
       Cascade_Cipher(BlockCipher* cipher1, BlockCipher* cipher2);
 
       ~Cascade_Cipher();
diff --git a/src/block/cast/cast128.h b/src/block/cast/cast128.h
index 048d2e43c..967e91938 100644
--- a/src/block/cast/cast128.h
+++ b/src/block/cast/cast128.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * CAST-128
 */
 class BOTAN_DLL CAST_128 : public BlockCipher
diff --git a/src/block/cast/cast256.h b/src/block/cast/cast256.h
index 170d94e77..c4a305671 100644
--- a/src/block/cast/cast256.h
+++ b/src/block/cast/cast256.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * CAST-256
 */
 class BOTAN_DLL CAST_256 : public BlockCipher
diff --git a/src/block/des/des.h b/src/block/des/des.h
index 32dd3daf6..1ae806850 100644
--- a/src/block/des/des.h
+++ b/src/block/des/des.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * DES
 */
 class BOTAN_DLL DES : public BlockCipher
@@ -32,7 +32,7 @@ class BOTAN_DLL DES : public BlockCipher
       SecureVector<u32bit, 32> round_key;
    };
 
-/*
+/**
 * Triple DES
 */
 class BOTAN_DLL TripleDES : public BlockCipher
diff --git a/src/block/des/desx.h b/src/block/des/desx.h
index 440574e9d..45a9d8479 100644
--- a/src/block/des/desx.h
+++ b/src/block/des/desx.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * DESX
 */
 class BOTAN_DLL DESX : public BlockCipher
diff --git a/src/block/gost_28147/gost_28147.h b/src/block/gost_28147/gost_28147.h
index 2ccb3214d..ec23466f4 100644
--- a/src/block/gost_28147/gost_28147.h
+++ b/src/block/gost_28147/gost_28147.h
@@ -21,14 +21,24 @@ namespace Botan {
 class BOTAN_DLL GOST_28147_89_Params
    {
    public:
+      /**
+      * @param row the row
+      * @param col the column
+      * @return sbox entry at this row/column
+      */
       byte sbox_entry(u32bit row, u32bit col) const;
 
+      /**
+      * @return name of this parameter set
+      */
       std::string param_name() const { return name; }
 
       /**
       * Default GOST parameters are the ones given in GOST R 34.11 for
       * testing purposes; these sboxes are also used by Crypto++, and,
-      * at least according to Wikipedia, the Central Bank of Russian Federation
+      * at least according to Wikipedia, the Central Bank of Russian
+      * Federation
+      * @param name of the parameter set
       */
       GOST_28147_89_Params(const std::string& name = "R3411_94_TestParam");
    private:
@@ -50,6 +60,9 @@ class BOTAN_DLL GOST_28147_89 : public BlockCipher
       std::string name() const { return "GOST-28147-89"; }
       BlockCipher* clone() const { return new GOST_28147_89(SBOX); }
 
+      /**
+      * @param params the sbox parameters to use
+      */
       GOST_28147_89(const GOST_28147_89_Params& params);
    private:
       GOST_28147_89(const SecureVector<u32bit, 1024>& other_SBOX) :
diff --git a/src/block/idea/idea.h b/src/block/idea/idea.h
index 1a9644d4e..e9ccf366d 100644
--- a/src/block/idea/idea.h
+++ b/src/block/idea/idea.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * IDEA
 */
 class BOTAN_DLL IDEA : public BlockCipher
@@ -26,8 +26,10 @@ class BOTAN_DLL IDEA : public BlockCipher
       BlockCipher* clone() const { return new IDEA; }
 
       IDEA() : BlockCipher(8, 16) {}
-   protected:
+   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.h b/src/block/idea_sse2/idea_sse2.h
index 657581d74..b00e0f400 100644
--- a/src/block/idea_sse2/idea_sse2.h
+++ b/src/block/idea_sse2/idea_sse2.h
@@ -12,13 +12,13 @@
 
 namespace Botan {
 
-/*
+/**
 * IDEA in SSE2
 */
 class BOTAN_DLL IDEA_SSE2 : public IDEA
    {
    public:
-      u32bit parallelism() const { return 16; }
+      u32bit parallelism() const { return 8; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
diff --git a/src/block/kasumi/kasumi.h b/src/block/kasumi/kasumi.h
index 827989a57..fda348ef3 100644
--- a/src/block/kasumi/kasumi.h
+++ b/src/block/kasumi/kasumi.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* KASUMI
+/**
+* KASUMI, the block cipher used in 3G telephony
 */
 class BOTAN_DLL KASUMI : public BlockCipher
    {
diff --git a/src/block/lion/lion.h b/src/block/lion/lion.h
index f24acdb72..bba4e6f30 100644
--- a/src/block/lion/lion.h
+++ b/src/block/lion/lion.h
@@ -14,8 +14,13 @@
 
 namespace Botan {
 
-/*
-* Lion
+/**
+* Lion is a block cipher construction designed by Ross Anderson and
+* Eli Biham, described in "Two Practical and Provably Secure Block
+* Ciphers: BEAR and LION". It has a variable block size and is
+* designed to encrypt very large blocks (up to a megabyte)
+
+* http://www.cl.cam.ac.uk/~rja14/Papers/bear-lion.pdf
 */
 class BOTAN_DLL Lion : public BlockCipher
    {
@@ -27,7 +32,15 @@ class BOTAN_DLL Lion : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const;
 
-      Lion(HashFunction*, StreamCipher*, u32bit);
+      /**
+      * @param hash the hash to use internally
+      * @param cipher the stream cipher to use internally
+      * @param block_size the size of the block to use
+      */
+      Lion(HashFunction* hash,
+           StreamCipher* cipher,
+           u32bit block_size);
+
       ~Lion() { delete hash; delete cipher; }
    private:
       void key_schedule(const byte[], u32bit);
diff --git a/src/block/lubyrack/lubyrack.h b/src/block/lubyrack/lubyrack.h
index 7249cf157..a69d2302f 100644
--- a/src/block/lubyrack/lubyrack.h
+++ b/src/block/lubyrack/lubyrack.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* Luby-Rackoff
+/**
+* Luby-Rackoff block cipher construction
 */
 class BOTAN_DLL LubyRackoff : public BlockCipher
    {
@@ -26,6 +26,9 @@ class BOTAN_DLL LubyRackoff : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const;
 
+      /**
+      * @param hash function to use to form the block cipher
+      */
       LubyRackoff(HashFunction* hash);
       ~LubyRackoff() { delete hash; }
    private:
diff --git a/src/block/mars/mars.h b/src/block/mars/mars.h
index f2a6d0197..f455ec5ca 100644
--- a/src/block/mars/mars.h
+++ b/src/block/mars/mars.h
@@ -12,6 +12,9 @@
 
 namespace Botan {
 
+/**
+* MARS, IBM's candidate for AES
+*/
 class BOTAN_DLL MARS : public BlockCipher
    {
    public:
diff --git a/src/block/misty1/misty1.h b/src/block/misty1/misty1.h
index 7b4d91def..a9bc12c7b 100644
--- a/src/block/misty1/misty1.h
+++ b/src/block/misty1/misty1.h
@@ -1,4 +1,4 @@
-/**
+/*
 * MISTY1
 * (C) 1999-2008 Jack Lloyd
 *
@@ -25,7 +25,11 @@ class BOTAN_DLL MISTY1 : public BlockCipher
       std::string name() const { return "MISTY1"; }
       BlockCipher* clone() const { return new MISTY1; }
 
-      MISTY1(u32bit = 8);
+      /**
+      * @param rounds the number of rounds. Must be 8 with the current
+      * implementation
+      */
+      MISTY1(u32bit rounds = 8);
    private:
       void key_schedule(const byte[], u32bit);
 
diff --git a/src/block/noekeon/noekeon.h b/src/block/noekeon/noekeon.h
index abeecbc64..018c1d1fd 100644
--- a/src/block/noekeon/noekeon.h
+++ b/src/block/noekeon/noekeon.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Noekeon
 */
 class BOTAN_DLL Noekeon : public BlockCipher
@@ -26,9 +26,13 @@ class BOTAN_DLL Noekeon : public BlockCipher
       BlockCipher* clone() const { return new Noekeon; }
 
       Noekeon() : BlockCipher(16, 16) {}
-   protected:
+   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/block/noekeon_simd/noekeon_simd.h b/src/block/noekeon_simd/noekeon_simd.h
index 55fdfbd22..507f17e21 100644
--- a/src/block/noekeon_simd/noekeon_simd.h
+++ b/src/block/noekeon_simd/noekeon_simd.h
@@ -12,13 +12,13 @@
 
 namespace Botan {
 
-/*
-* Noekeon
+/**
+* Noekeon implementation using SIMD operations
 */
 class BOTAN_DLL Noekeon_SIMD : public Noekeon
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
diff --git a/src/block/rc2/rc2.h b/src/block/rc2/rc2.h
index dd0295572..c16680347 100644
--- a/src/block/rc2/rc2.h
+++ b/src/block/rc2/rc2.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * RC2
 */
 class BOTAN_DLL RC2 : public BlockCipher
@@ -21,7 +21,12 @@ class BOTAN_DLL RC2 : public BlockCipher
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
 
-      static byte EKB_code(u32bit);
+      /**
+      * Return the code of the effective key bits
+      * @param bits key length
+      * @return EKB code
+      */
+      static byte EKB_code(u32bit bits);
 
       void clear() { K.clear(); }
       std::string name() const { return "RC2"; }
diff --git a/src/block/rc5/rc5.h b/src/block/rc5/rc5.h
index 82931c1d2..385c6b2b1 100644
--- a/src/block/rc5/rc5.h
+++ b/src/block/rc5/rc5.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * RC5
 */
 class BOTAN_DLL RC5 : public BlockCipher
@@ -25,7 +25,11 @@ class BOTAN_DLL RC5 : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const { return new RC5(ROUNDS); }
 
-      RC5(u32bit);
+      /**
+      * @param rounds the number of RC5 rounds to run. Must be between
+      * 8 and 32 and a multiple of 4.
+      */
+      RC5(u32bit rounds);
    private:
       void key_schedule(const byte[], u32bit);
       SecureVector<u32bit> S;
diff --git a/src/block/rc6/rc6.h b/src/block/rc6/rc6.h
index cc1534ee2..9b2d587fa 100644
--- a/src/block/rc6/rc6.h
+++ b/src/block/rc6/rc6.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* RC6
+/**
+* RC6, Ron Rivest's AES candidate
 */
 class BOTAN_DLL RC6 : public BlockCipher
    {
diff --git a/src/block/safer/safer_sk.h b/src/block/safer/safer_sk.h
index 80d2dc069..c93797602 100644
--- a/src/block/safer/safer_sk.h
+++ b/src/block/safer/safer_sk.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * SAFER-SK
 */
 class BOTAN_DLL SAFER_SK : public BlockCipher
@@ -25,7 +25,11 @@ class BOTAN_DLL SAFER_SK : public BlockCipher
       std::string name() const;
       BlockCipher* clone() const;
 
-      SAFER_SK(u32bit);
+      /**
+      * @param rounds the number of rounds to use - must be between 1
+      * and 13
+      */
+      SAFER_SK(u32bit rounds);
    private:
       void key_schedule(const byte[], u32bit);
 
diff --git a/src/block/seed/seed.h b/src/block/seed/seed.h
index e56b77dbb..0c80199ad 100644
--- a/src/block/seed/seed.h
+++ b/src/block/seed/seed.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* SEED
+/**
+* SEED, a Korean block cipher
 */
 class BOTAN_DLL SEED : public BlockCipher
    {
diff --git a/src/block/serpent/serpent.h b/src/block/serpent/serpent.h
index 37ce10c7b..1c13d00f9 100644
--- a/src/block/serpent/serpent.h
+++ b/src/block/serpent/serpent.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Serpent
+/**
+* Serpent, an AES finalist
 */
 class BOTAN_DLL Serpent : public BlockCipher
    {
@@ -26,7 +26,7 @@ class BOTAN_DLL Serpent : public BlockCipher
       BlockCipher* clone() const { return new Serpent; }
       Serpent() : BlockCipher(16, 16, 32, 8) {}
    protected:
-      void key_schedule(const byte[], u32bit);
+      void key_schedule(const byte key[], u32bit length);
 
       SecureVector<u32bit, 132> round_key;
    };
diff --git a/src/block/serpent_ia32/serp_ia32.h b/src/block/serpent_ia32/serp_ia32.h
index dc6beaf13..229a2042b 100644
--- a/src/block/serpent_ia32/serp_ia32.h
+++ b/src/block/serpent_ia32/serp_ia32.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Serpent
+/**
+* Serpent implementation in x86 assembly
 */
 class BOTAN_DLL Serpent_IA32 : public Serpent
    {
diff --git a/src/block/serpent_simd/serp_simd.h b/src/block/serpent_simd/serp_simd.h
index dc2b08736..f0a11fc93 100644
--- a/src/block/serpent_simd/serp_simd.h
+++ b/src/block/serpent_simd/serp_simd.h
@@ -12,13 +12,13 @@
 
 namespace Botan {
 
-/*
-* Serpent
+/**
+* Serpent implementation using SIMD
 */
 class BOTAN_DLL Serpent_SIMD : public Serpent
    {
    public:
-      u32bit parallelism() const { return 8; }
+      u32bit parallelism() const { return 4; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
diff --git a/src/block/skipjack/skipjack.h b/src/block/skipjack/skipjack.h
index d481aee08..29978efc7 100644
--- a/src/block/skipjack/skipjack.h
+++ b/src/block/skipjack/skipjack.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Skipjack
+/**
+* Skipjack, a NSA designed cipher used in Fortezza
 */
 class BOTAN_DLL Skipjack : public BlockCipher
    {
diff --git a/src/block/square/square.h b/src/block/square/square.h
index 8e1f7f815..a17771f11 100644
--- a/src/block/square/square.h
+++ b/src/block/square/square.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Square
 */
 class BOTAN_DLL Square : public BlockCipher
diff --git a/src/block/tea/tea.h b/src/block/tea/tea.h
index 152c9a905..128f42080 100644
--- a/src/block/tea/tea.h
+++ b/src/block/tea/tea.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * TEA
 */
 class BOTAN_DLL TEA : public BlockCipher
diff --git a/src/block/twofish/twofish.h b/src/block/twofish/twofish.h
index 7600abca8..3191dc963 100644
--- a/src/block/twofish/twofish.h
+++ b/src/block/twofish/twofish.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Twofish
+/**
+* Twofish, an AES finalist
 */
 class BOTAN_DLL Twofish : public BlockCipher
    {
diff --git a/src/block/xtea/xtea.h b/src/block/xtea/xtea.h
index 940992dfa..b16cdf555 100644
--- a/src/block/xtea/xtea.h
+++ b/src/block/xtea/xtea.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * XTEA
 */
 class BOTAN_DLL XTEA : public BlockCipher
diff --git a/src/block/xtea_simd/xtea_simd.h b/src/block/xtea_simd/xtea_simd.h
index 04a4977ae..87eeb433b 100644
--- a/src/block/xtea_simd/xtea_simd.h
+++ b/src/block/xtea_simd/xtea_simd.h
@@ -12,13 +12,13 @@
 
 namespace Botan {
 
-/*
-* XTEA (SIMD variant)
+/**
+* XTEA implemented using SIMD operations
 */
 class BOTAN_DLL XTEA_SIMD : public XTEA
    {
    public:
-      u32bit parallelism() const { return 16; }
+      u32bit parallelism() const { return 8; }
 
       void encrypt_n(const byte in[], byte out[], u32bit blocks) const;
       void decrypt_n(const byte in[], byte out[], u32bit blocks) const;
diff --git a/src/build-data/arch/amd64.txt b/src/build-data/arch/amd64.txt
index b0cf546d7..6b721805e 100644
--- a/src/build-data/arch/amd64.txt
+++ b/src/build-data/arch/amd64.txt
@@ -29,10 +29,12 @@ opteron -> k8
 amdopteron -> k8
 athlon64 -> k8
 barcelona -> k10
+
+corei5cpum520 -> westmere
 </submodel_aliases>
 
 <isa_extn>
 sse2:all
 ssse3:core2,nehalem,westmere
-aes_ni:westmere
+aes-ni:westmere
 </isa_extn>
diff --git a/src/build-data/botan.doxy.in b/src/build-data/botan.doxy.in
index 87d6e58eb..2f76a756b 100644
--- a/src/build-data/botan.doxy.in
+++ b/src/build-data/botan.doxy.in
@@ -13,7 +13,7 @@ BRIEF_MEMBER_DESC      = YES
 REPEAT_BRIEF           = YES
 ABBREVIATE_BRIEF       =
 ALWAYS_DETAILED_SEC    = NO
-INLINE_INHERITED_MEMB  = NO
+INLINE_INHERITED_MEMB  = YES
 FULL_PATH_NAMES        = YES
 STRIP_FROM_PATH        =
 STRIP_FROM_INC_PATH    =
@@ -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
@@ -40,7 +39,7 @@ TYPEDEF_HIDES_STRUCT   = NO
 EXTRACT_ALL            = YES
 EXTRACT_PRIVATE        = NO
 EXTRACT_STATIC         = NO
-EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_CLASSES  = NO
 EXTRACT_LOCAL_METHODS  = NO
 EXTRACT_ANON_NSPACES   = NO
 HIDE_UNDOC_MEMBERS     = NO
@@ -69,7 +68,7 @@ FILE_VERSION_FILTER    =
 #---------------------------------------------------------------------------
 QUIET                  = YES
 WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_UNDOCUMENTED   = YES
 WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = NO
 WARN_FORMAT            = "$file:$line: $text"
@@ -83,7 +82,7 @@ FILE_PATTERNS          =
 RECURSIVE              = YES
 EXCLUDE                =
 EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = */wrap/*
 EXCLUDE_SYMBOLS        =
 EXAMPLE_PATH           =
 EXAMPLE_PATTERNS       =
diff --git a/src/build-data/buildh.in b/src/build-data/buildh.in
index 90d274d58..6a203234a 100644
--- a/src/build-data/buildh.in
+++ b/src/build-data/buildh.in
@@ -8,6 +8,8 @@
 #define BOTAN_VERSION_MINOR %{version_minor}
 #define BOTAN_VERSION_PATCH %{version_patch}
 
+#define BOTAN_VERSION_DATESTAMP %{version_datestamp}
+
 #ifndef BOTAN_DLL
   #define BOTAN_DLL %{dll_import_flags}
 #endif
@@ -15,6 +17,7 @@
 /* Chunk sizes */
 #define BOTAN_DEFAULT_BUFFER_SIZE 4096
 #define BOTAN_MEM_POOL_CHUNK_SIZE 64*1024
+#define BOTAN_BLOCK_CIPHER_PAR_MULT 4
 
 /* BigInt toggles */
 #define BOTAN_MP_WORD_BITS %{mp_bits}
diff --git a/src/build-data/cc/gcc.txt b/src/build-data/cc/gcc.txt
index d133065a8..ebb239c86 100644
--- a/src/build-data/cc/gcc.txt
+++ b/src/build-data/cc/gcc.txt
@@ -10,7 +10,7 @@ add_lib_option -l
 
 lang_flags "-ansi -std=c++0x"
 #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"
@@ -29,7 +29,7 @@ default -> "$(CXX) -shared -fPIC -Wl,-soname,$(SONAME)"
 # AIX doesn't seem to have soname support (weird...)
 aix     -> "$(CXX) -shared -fPIC"
 
-darwin  -> "$(CXX) -dynamiclib -fPIC -install_name $(SONAME)"
+darwin  -> "$(CXX) -dynamiclib -fPIC -install_name $(LIBDIR)/$(SONAME)"
 hpux    -> "$(CXX) -shared -fPIC -Wl,+h,$(SONAME)"
 solaris -> "$(CXX) -shared -fPIC -Wl,-h,$(SONAME)"
 # Gotta use ld directly on BeOS, their GCC is busted
diff --git a/src/build-data/cc/msvc.txt b/src/build-data/cc/msvc.txt
index 273f1c5c0..24d91b3f3 100644
--- a/src/build-data/cc/msvc.txt
+++ b/src/build-data/cc/msvc.txt
@@ -11,7 +11,7 @@ add_lib_option ""
 no_debug_flags "/O2"
 debug_flags "/Od /Zi /DDEBUG"
 check_opt_flags "/O2 /D_CONSOLE"
-lang_flags "/EHsc /GR"
+lang_flags "/EHs /GR"
 warning_flags "/W3 /wd4275"
 
 shared_flags "/DBOTAN_DLL=__declspec(dllexport)"
diff --git a/src/build-data/innosetup.in b/src/build-data/innosetup.in
index c3e0f1ebd..0a7eeb8f6 100644
--- a/src/build-data/innosetup.in
+++ b/src/build-data/innosetup.in
@@ -8,12 +8,16 @@ AppPublisher=Jack Lloyd
 AppPublisherURL=http://botan.randombit.net/
 AppVersion=%{version}
 
-VersionInfoCopyright=Copyright (C) 1999-2009 Jack Lloyd and others
+VersionInfoCopyright=Copyright (C) 1999-2010 Jack Lloyd and others
 VersionInfoVersion=%{version_major}.%{version_minor}.%{version_patch}.0
 
 ; Require at least Windows 98 or 2000
 MinVersion=4.1,5.0
 
+; Uncomment for 64 bit builds
+;ArchitecturesAllowed = x64
+;ArchitecturesInstallIn64BitMode = x64
+
 DefaultDirName={pf}\botan
 DefaultGroupName=botan
 
diff --git a/src/build-data/makefile/nmake.in b/src/build-data/makefile/nmake.in
index 212825131..9928f3d4e 100644
--- a/src/build-data/makefile/nmake.in
+++ b/src/build-data/makefile/nmake.in
@@ -15,10 +15,6 @@ VERSION       = %{version}
 ### Installation Settings
 DESTDIR       = %{prefix}
 
-LIBDIR        = $(DESTDIR)\%{libdir}
-HEADERDIR     = $(DESTDIR)\%{includedir}\botan
-DOCDIR        = $(DESTDIR)\%{docdir}\botan-$(VERSION)
-
 ### Aliases for Common Programs
 AR            = %{ar_command}
 CD            = @cd
@@ -86,4 +82,6 @@ distclean: clean
 
 ### Install Commands
 install: $(LIBRARIES)
-	$(ECHO) "Install command not implemented"
+	-$(MKDIR) $(DESTDIR)\include\botan
+	$(INSTALL_CMD) botan.* $(DESTDIR)
+	$(INSTALL_CMD) build\include\botan\*.h $(DESTDIR)\include\botan
diff --git a/src/cert/cvc/cvc_ado.h b/src/cert/cvc/cvc_ado.h
index 230ee8b8d..65a39fd91 100644
--- a/src/cert/cvc/cvc_ado.h
+++ b/src/cert/cvc/cvc_ado.h
@@ -41,6 +41,7 @@ class BOTAN_DLL EAC1_1_ADO : public EAC1_1_obj<EAC1_1_ADO>
       * Create a signed CVC ADO request from to be signed (TBS) data
       * @param signer the signer used to sign the CVC ADO request
       * @param tbs_bits the TBS data to sign
+      * @param rng a random number generator
       */
       static MemoryVector<byte> make_signed(
          PK_Signer& signer,
diff --git a/src/cert/cvc/cvc_cert.h b/src/cert/cvc/cvc_cert.h
index 12bc41a9c..69d0d824a 100644
--- a/src/cert/cvc/cvc_cert.h
+++ b/src/cert/cvc/cvc_cert.h
@@ -92,7 +92,8 @@ inline bool operator!=(EAC1_1_CVC const& lhs, EAC1_1_CVC const& rhs)
 * @param holder_auth_templ the holder authorization value byte to
 * appear in the CHAT of the certificate
 * @param ced the CED to appear in the certificate
-* @param ced the CEX to appear in the certificate
+* @param cex the CEX to appear in the certificate
+* @param rng a random number generator
 */
 EAC1_1_CVC BOTAN_DLL make_cvc_cert(PK_Signer& signer,
                                    const MemoryRegion<byte>& public_key,
diff --git a/src/cert/cvc/cvc_gen_cert.h b/src/cert/cvc/cvc_gen_cert.h
index 4f98041e3..7b125c10d 100644
--- a/src/cert/cvc/cvc_gen_cert.h
+++ b/src/cert/cvc/cvc_gen_cert.h
@@ -70,6 +70,7 @@ class EAC1_1_gen_CVC : public EAC1_1_obj<Derived> // CRTP continuation from EAC1
       * Create a signed generalized CVC object.
       * @param signer the signer used to sign this object
       * @param tbs_bits the body the generalized CVC object to be signed
+      * @param rng a random number generator
       * @result the DER encoded signed generalized CVC object
       */
       static MemoryVector<byte> make_signed(
diff --git a/src/cert/cvc/cvc_self.h b/src/cert/cvc/cvc_self.h
index fb24ecd3a..f7bf6d5d8 100644
--- a/src/cert/cvc/cvc_self.h
+++ b/src/cert/cvc/cvc_self.h
@@ -97,7 +97,8 @@ namespace DE_EAC {
 * shall be entitled to read the biometrical iris image
 * @param fingerpr indicates whether the entity associated with the certificate
 * shall be entitled to read the biometrical fingerprint image
-* @param rng the rng to use
+* @param cvca_validity_months length of time in months this will be valid
+* @param rng a random number generator
 * @result the CVCA certificate created
 */
 EAC1_1_CVC BOTAN_DLL create_cvca(Private_Key const& priv_key,
@@ -146,8 +147,10 @@ EAC1_1_Req BOTAN_DLL create_cvc_req(Private_Key const& priv_key,
 * @param seqnr the sequence number of the certificate to be created
 * @param seqnr_len the number of digits the sequence number will be
 * encoded in
-* @param domestic indicates whether to sign a domestic or a foreign certificate:
-* set to true for domestic
+* @param domestic indicates whether to sign a domestic or a foreign
+* certificate: set to true for domestic
+* @param dvca_validity_months validity period in months
+* @param ca_is_validity_months validity period in months
 * @param rng a random number generator
 * @result the new certificate
 *
diff --git a/src/cert/cvc/eac_asn_obj.h b/src/cert/cvc/eac_asn_obj.h
index 3ab57d7e4..dc4f82578 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;
 
@@ -71,19 +71,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 { return year; }
 
       /**
       * Get the month value of this objects.
-      * @return the month value
+      * @return month value
       */
       u32bit get_month() const { return month; }
 
       /**
       * Get the day value of this objects.
-      * @return the day value
+      * @return day value
       */
       u32bit get_day() const { return day; }
 
@@ -170,13 +170,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/eac_obj.h b/src/cert/cvc/eac_obj.h
index 66752b10c..eb6db3369 100644
--- a/src/cert/cvc/eac_obj.h
+++ b/src/cert/cvc/eac_obj.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * TR03110 v1.1 EAC CV Certificate
 */
 template<typename Derived> // CRTP is used enable the call sequence:
diff --git a/src/cert/cvc/ecdsa_sig.h b/src/cert/cvc/ecdsa_sig.h
index 1397a92b1..a92052470 100644
--- a/src/cert/cvc/ecdsa_sig.h
+++ b/src/cert/cvc/ecdsa_sig.h
@@ -15,6 +15,9 @@
 
 namespace Botan {
 
+/**
+* Class representing an ECDSA signature
+*/
 class BOTAN_DLL ECDSA_Signature
    {
    public:
diff --git a/src/cert/cvc/signed_obj.h b/src/cert/cvc/signed_obj.h
index 0e7dd6bdb..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
       */
 
       /*
@@ -50,6 +50,7 @@ class BOTAN_DLL EAC_Signed_Object
       /**
       * Check the signature of this object.
       * @param key the public key associated with this signed object
+      * @param sig the signature we are checking
       * @return true if the signature was created by the private key
       * associated with this public key
       */
@@ -59,19 +60,20 @@ class BOTAN_DLL EAC_Signed_Object
       /**
       * Write this object DER encoded into a specified pipe.
       * @param pipe the pipe to write the encoded object to
-      * @param enc the encoding type to use
+      * @param encoding the encoding type to use
       */
-      virtual void encode(Pipe&, X509_Encoding = PEM) const = 0;
+      virtual void encode(Pipe& pipe,
+                          X509_Encoding encoding = PEM) const = 0;
 
       /**
       * 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/certstor.h b/src/cert/x509/certstor.h
index d5004e366..2e39a7178 100644
--- a/src/cert/x509/certstor.h
+++ b/src/cert/x509/certstor.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Certificate Store Interface
 */
 class BOTAN_DLL Certificate_Store
diff --git a/src/cert/x509/crl_ent.h b/src/cert/x509/crl_ent.h
index 050356c84..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; }
 
@@ -49,7 +49,8 @@ class BOTAN_DLL CRL_Entry : public ASN1_Object
       * @param cert the certificate to revoke
       * @param reason the reason code to set in the entry
       */
-      CRL_Entry(const X509_Certificate&, CRL_Code = UNSPECIFIED);
+      CRL_Entry(const X509_Certificate& cert,
+                CRL_Code reason = UNSPECIFIED);
 
    private:
       bool throw_on_unknown_critical;
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 b680bd0e4..7aca26d03 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;
@@ -71,6 +71,7 @@ class BOTAN_DLL X509_CA
       * @param signer a signing object
       * @param rng a random number generator
       * @param sig_algo the signature algorithm identifier
+      * @param pub_key the serialized public key
       * @param not_before the start time of the certificate
       * @param not_after the end time of the certificate
       * @param issuer_dn the DN of the issuer
@@ -92,6 +93,7 @@ class BOTAN_DLL X509_CA
       * Create a new CA object.
       * @param ca_certificate the certificate of the CA
       * @param key the private key of the CA
+      * @param hash_fn name of a hash function to use for signing
       */
       X509_CA(const X509_Certificate& ca_certificate,
               const Private_Key& key,
diff --git a/src/cert/x509/x509_crl.h b/src/cert/x509/x509_crl.h
index a7903e7e6..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,31 +49,35 @@ 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;
 
       /**
       * Construct a CRL from a data source.
       * @param source the data source providing the DER or PEM encoded CRL.
+      * @param throw_on_unknown_critical should we throw an exception
+      * if an unknown CRL extension marked as critical is encountered.
       */
-      X509_CRL(DataSource&, bool throw_on_unknown_critical = false);
+      X509_CRL(DataSource& source, bool throw_on_unknown_critical = false);
 
       /**
       * Construct a CRL from a file containing the DER or PEM encoded CRL.
       * @param filename the name of the CRL file
+      * @param throw_on_unknown_critical should we throw an exception
+      * if an unknown CRL extension marked as critical is encountered.
       */
       X509_CRL(const std::string& filename,
                bool throw_on_unknown_critical = false);
diff --git a/src/cert/x509/x509_ext.h b/src/cert/x509/x509_ext.h
index a5bfd357f..213a077a2 100644
--- a/src/cert/x509/x509_ext.h
+++ b/src/cert/x509/x509_ext.h
@@ -16,18 +16,40 @@
 
 namespace Botan {
 
-/*
+/**
 * X.509 Certificate Extension
 */
 class BOTAN_DLL Certificate_Extension
    {
    public:
+      /**
+      * @return OID representing this extension
+      */
       OID oid_of() const;
 
+      /**
+      * Make a copy of this extension
+      * @return copy of this
+      */
       virtual Certificate_Extension* copy() const = 0;
 
-      virtual void contents_to(Data_Store&, Data_Store&) const = 0;
+      /*
+      * Add the contents of this extension into the information
+      * for the subject and/or issuer, as necessary.
+      * @param subject the subject info
+      * @param issuer the issuer info
+      */
+      virtual void contents_to(Data_Store& subject,
+                               Data_Store& issuer) const = 0;
+
+      /*
+      * @return short readable name
+      */
       virtual std::string config_id() const = 0;
+
+      /*
+      * @return specific OID name
+      */
       virtual std::string oid_name() const = 0;
 
       virtual ~Certificate_Extension() {}
@@ -38,7 +60,7 @@ class BOTAN_DLL Certificate_Extension
       virtual void decode_inner(const MemoryRegion<byte>&) = 0;
    };
 
-/*
+/**
 * X.509 Certificate Extension List
 */
 class BOTAN_DLL Extensions : public ASN1_Object
@@ -65,7 +87,7 @@ class BOTAN_DLL Extensions : public ASN1_Object
 
 namespace Cert_Extension {
 
-/*
+/**
 * Basic Constraints Extension
 */
 class BOTAN_DLL Basic_Constraints : public Certificate_Extension
@@ -91,7 +113,7 @@ class BOTAN_DLL Basic_Constraints : public Certificate_Extension
       u32bit path_limit;
    };
 
-/*
+/**
 * Key Usage Constraints Extension
 */
 class BOTAN_DLL Key_Usage : public Certificate_Extension
@@ -114,7 +136,7 @@ class BOTAN_DLL Key_Usage : public Certificate_Extension
       Key_Constraints constraints;
    };
 
-/*
+/**
 * Subject Key Identifier Extension
 */
 class BOTAN_DLL Subject_Key_ID : public Certificate_Extension
@@ -138,7 +160,7 @@ class BOTAN_DLL Subject_Key_ID : public Certificate_Extension
       MemoryVector<byte> key_id;
    };
 
-/*
+/**
 * Authority Key Identifier Extension
 */
 class BOTAN_DLL Authority_Key_ID : public Certificate_Extension
@@ -162,7 +184,7 @@ class BOTAN_DLL Authority_Key_ID : public Certificate_Extension
       MemoryVector<byte> key_id;
    };
 
-/*
+/**
 * Alternative Name Extension Base Class
 */
 class BOTAN_DLL Alternative_Name : public Certificate_Extension
@@ -188,7 +210,7 @@ class BOTAN_DLL Alternative_Name : public Certificate_Extension
       AlternativeName alt_name;
    };
 
-/*
+/**
 * Subject Alternative Name Extension
 */
 class BOTAN_DLL Subject_Alternative_Name : public Alternative_Name
@@ -200,7 +222,7 @@ class BOTAN_DLL Subject_Alternative_Name : public Alternative_Name
       Subject_Alternative_Name(const AlternativeName& = AlternativeName());
    };
 
-/*
+/**
 * Issuer Alternative Name Extension
 */
 class BOTAN_DLL Issuer_Alternative_Name : public Alternative_Name
@@ -212,7 +234,7 @@ class BOTAN_DLL Issuer_Alternative_Name : public Alternative_Name
       Issuer_Alternative_Name(const AlternativeName& = AlternativeName());
    };
 
-/*
+/**
 * Extended Key Usage Extension
 */
 class BOTAN_DLL Extended_Key_Usage : public Certificate_Extension
@@ -236,7 +258,7 @@ class BOTAN_DLL Extended_Key_Usage : public Certificate_Extension
       std::vector<OID> oids;
    };
 
-/*
+/**
 * Certificate Policies Extension
 */
 class BOTAN_DLL Certificate_Policies : public Certificate_Extension
@@ -261,7 +283,7 @@ class BOTAN_DLL Certificate_Policies : public Certificate_Extension
       std::vector<OID> oids;
    };
 
-/*
+/**
 * CRL Number Extension
 */
 class BOTAN_DLL CRL_Number : public Certificate_Extension
@@ -286,7 +308,7 @@ class BOTAN_DLL CRL_Number : public Certificate_Extension
       u32bit crl_number;
    };
 
-/*
+/**
 * CRL Entry Reason Code Extension
 */
 class BOTAN_DLL CRL_ReasonCode : public Certificate_Extension
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.cpp b/src/cert/x509/x509self.cpp
index d87c5e060..6e570d3b6 100644
--- a/src/cert/x509/x509self.cpp
+++ b/src/cert/x509/x509self.cpp
@@ -18,22 +18,6 @@ namespace Botan {
 namespace {
 
 /*
-* Shared setup for self-signed items
-*/
-MemoryVector<byte> shared_setup(const X509_Cert_Options& opts,
-                                const Private_Key& key)
-   {
-   opts.sanity_check();
-
-   Pipe key_encoder;
-   key_encoder.start_msg();
-   X509::encode(key, key_encoder, RAW_BER);
-   key_encoder.end_msg();
-
-   return key_encoder.read_all();
-   }
-
-/*
 * Load information from the X509_Cert_Options
 */
 void load_info(const X509_Cert_Options& opts, X509_DN& subject_dn,
@@ -67,7 +51,9 @@ X509_Certificate create_self_signed_cert(const X509_Cert_Options& opts,
    X509_DN subject_dn;
    AlternativeName subject_alt;
 
-   MemoryVector<byte> pub_key = shared_setup(opts, key);
+   opts.sanity_check();
+
+   MemoryVector<byte> pub_key = X509::BER_encode(key);
    std::unique_ptr<PK_Signer> signer(choose_sig_format(key, hash_fn, sig_algo));
    load_info(opts, subject_dn, subject_alt);
 
@@ -111,7 +97,9 @@ PKCS10_Request create_cert_req(const X509_Cert_Options& opts,
    X509_DN subject_dn;
    AlternativeName subject_alt;
 
-   MemoryVector<byte> pub_key = shared_setup(opts, key);
+   opts.sanity_check();
+
+   MemoryVector<byte> pub_key = X509::BER_encode(key);
    std::unique_ptr<PK_Signer> signer(choose_sig_format(key, hash_fn, sig_algo));
    load_info(opts, subject_dn, subject_alt);
 
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/cert/x509/x509stor.h b/src/cert/x509/x509stor.h
index 1911c6b6a..c375c19cb 100644
--- a/src/cert/x509/x509stor.h
+++ b/src/cert/x509/x509stor.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * X.509 Certificate Validation Result
 */
 enum X509_Code {
@@ -43,7 +43,7 @@ enum X509_Code {
    CA_CERT_NOT_FOR_CRL_ISSUER
 };
 
-/*
+/**
 * X.509 Certificate Store
 */
 class BOTAN_DLL X509_Store
@@ -71,20 +71,6 @@ class BOTAN_DLL X509_Store
       std::vector<X509_Certificate> get_cert_chain(const X509_Certificate&);
       std::string PEM_encode() const;
 
-      /*
-      * Made CRL_Data public for XLC for Cell 0.9, otherwise cannot
-      * instantiate member variable std::vector<CRL_Data> revoked
-      */
-      class BOTAN_DLL CRL_Data
-         {
-         public:
-            X509_DN issuer;
-            MemoryVector<byte> serial, auth_key_id;
-            bool operator==(const CRL_Data&) const;
-            bool operator!=(const CRL_Data&) const;
-            bool operator<(const CRL_Data&) const;
-         };
-
       X509_Code add_crl(const X509_CRL&);
       void add_cert(const X509_Certificate&, bool = false);
       void add_certs(DataSource&);
@@ -106,6 +92,18 @@ class BOTAN_DLL X509_Store
       X509_Store(const X509_Store&);
       ~X509_Store();
    private:
+      X509_Store& operator=(const X509_Store&) { return (*this); }
+
+      class BOTAN_DLL CRL_Data
+         {
+         public:
+            X509_DN issuer;
+            MemoryVector<byte> serial, auth_key_id;
+            bool operator==(const CRL_Data&) const;
+            bool operator!=(const CRL_Data&) const;
+            bool operator<(const CRL_Data&) const;
+         };
+
       class BOTAN_DLL Cert_Info
          {
          public:
diff --git a/src/checksum/adler32/adler32.h b/src/checksum/adler32/adler32.h
index 79804a842..8cbd67f10 100644
--- a/src/checksum/adler32/adler32.h
+++ b/src/checksum/adler32/adler32.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Adler32
+/**
+* The Adler32 checksum, used in zlib
 */
 class BOTAN_DLL Adler32 : public HashFunction
    {
diff --git a/src/checksum/crc24/crc24.h b/src/checksum/crc24/crc24.h
index f59ac4a45..2fc5af2ff 100644
--- a/src/checksum/crc24/crc24.h
+++ b/src/checksum/crc24/crc24.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* CRC24
+/**
+* 24-bit cyclic redundancy check
 */
 class BOTAN_DLL CRC24 : public HashFunction
    {
diff --git a/src/checksum/crc32/crc32.h b/src/checksum/crc32/crc32.h
index 998e8489e..9fd69670d 100644
--- a/src/checksum/crc32/crc32.h
+++ b/src/checksum/crc32/crc32.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* CRC32
+/**
+* 32-bit cyclic redundancy check
 */
 class BOTAN_DLL CRC32 : public HashFunction
    {
diff --git a/src/cms/cms_dec.h b/src/cms/cms_dec.h
index a00b44766..53d7114d6 100644
--- a/src/cms/cms_dec.h
+++ b/src/cms/cms_dec.h
@@ -16,7 +16,7 @@
 
 namespace Botan {
 
-/*
+/**
 * CMS Decoding Operation
 */
 class BOTAN_DLL CMS_Decoder
diff --git a/src/cms/cms_enc.h b/src/cms/cms_enc.h
index ec2fdf3b3..f8e9a5a8f 100644
--- a/src/cms/cms_enc.h
+++ b/src/cms/cms_enc.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * CMS Encoding Operation
 */
 class BOTAN_DLL CMS_Encoder
diff --git a/src/codec/openpgp/openpgp.cpp b/src/codec/openpgp/openpgp.cpp
index f55caf1c8..ca1ea6d9c 100644
--- a/src/codec/openpgp/openpgp.cpp
+++ b/src/codec/openpgp/openpgp.cpp
@@ -13,14 +13,13 @@
 
 namespace Botan {
 
-namespace OpenPGP {
-
 /*
 * OpenPGP Base64 encoding
 */
-std::string encode(const byte input[], u32bit length,
-                   const std::string& label,
-                   const std::map<std::string, std::string>& headers)
+std::string PGP_encode(
+   const byte input[], u32bit length,
+   const std::string& label,
+   const std::map<std::string, std::string>& headers)
    {
    const std::string PGP_HEADER = "-----BEGIN PGP " + label + "-----\n";
    const std::string PGP_TRAILER = "-----END PGP " + label + "-----\n";
@@ -58,18 +57,19 @@ std::string encode(const byte input[], u32bit length,
 /*
 * OpenPGP Base64 encoding
 */
-std::string encode(const byte input[], u32bit length,
-                   const std::string& type)
+std::string PGP_encode(const byte input[], u32bit length,
+                       const std::string& type)
    {
    std::map<std::string, std::string> empty;
-   return encode(input, length, type, empty);
+   return PGP_encode(input, length, type, empty);
    }
 
 /*
 * OpenPGP Base64 decoding
 */
-SecureVector<byte> decode(DataSource& source, std::string& label,
-                          std::map<std::string, std::string>& headers)
+SecureVector<byte> PGP_decode(DataSource& source,
+                              std::string& label,
+                              std::map<std::string, std::string>& headers)
    {
    const u32bit RANDOM_CHAR_LIMIT = 5;
 
@@ -186,13 +186,11 @@ SecureVector<byte> decode(DataSource& source, std::string& label,
 /*
 * OpenPGP Base64 decoding
 */
-SecureVector<byte> decode(DataSource& source, std::string& label)
+SecureVector<byte> PGP_decode(DataSource& source, std::string& label)
    {
    std::map<std::string, std::string> ignored;
-   return decode(source, label, ignored);
+   return PGP_decode(source, label, ignored);
    }
 
 }
 
-}
-
diff --git a/src/codec/openpgp/openpgp.h b/src/codec/openpgp/openpgp.h
index 7021d5675..1e2cf10f0 100644
--- a/src/codec/openpgp/openpgp.h
+++ b/src/codec/openpgp/openpgp.h
@@ -14,20 +14,47 @@
 
 namespace Botan {
 
-namespace OpenPGP {
-
-/*
-* OpenPGP Base64 encoding/decoding
+/**
+* @param input the input data
+* @param length length of input in bytes
+* @param label the human-readable label
+* @param headers a set of key/value pairs included in the header
 */
-BOTAN_DLL std::string encode(const byte[], u32bit, const std::string&,
-                                  const std::map<std::string, std::string>&);
-BOTAN_DLL SecureVector<byte> decode(DataSource&, std::string&,
-                                         std::map<std::string, std::string>&);
-
-BOTAN_DLL std::string encode(const byte[], u32bit, const std::string&);
-BOTAN_DLL SecureVector<byte> decode(DataSource&, std::string&);
-
-}
+BOTAN_DLL std::string PGP_encode(
+   const byte input[],
+   u32bit length,
+   const std::string& label,
+   const std::map<std::string, std::string>& headers);
+
+/**
+* @param input the input data
+* @param length length of input in bytes
+* @param label the human-readable label
+*/
+BOTAN_DLL std::string PGP_encode(
+   const byte input[],
+   u32bit length,
+   const std::string& label);
+
+/**
+* @param source the input source
+* @param label is set to the human-readable label
+* @param headers is set to any headers
+* @return decoded output as raw binary
+*/
+BOTAN_DLL SecureVector<byte> PGP_decode(
+   DataSource& source,
+   std::string& label,
+   std::map<std::string, std::string>& headers);
+
+/**
+* @param source the input source
+* @param label is set to the human-readable label
+* @return decoded output as raw binary
+*/
+BOTAN_DLL SecureVector<byte> PGP_decode(
+   DataSource& source,
+   std::string& label);
 
 }
 
diff --git a/src/constructs/aont/package.cpp b/src/constructs/aont/package.cpp
index 5d1e674ca..e10087060 100644
--- a/src/constructs/aont/package.cpp
+++ b/src/constructs/aont/package.cpp
@@ -14,12 +14,10 @@
 
 namespace Botan {
 
-namespace AllOrNothingTransform {
-
-void package(RandomNumberGenerator& rng,
-             BlockCipher* cipher,
-             const byte input[], u32bit input_len,
-             byte output[])
+void aont_package(RandomNumberGenerator& rng,
+                  BlockCipher* cipher,
+                  const byte input[], u32bit input_len,
+                  byte output[])
    {
    if(!cipher->valid_keylength(cipher->BLOCK_SIZE))
       throw Invalid_Argument("AONT::package: Invalid cipher");
@@ -66,9 +64,9 @@ void package(RandomNumberGenerator& rng,
    xor_buf(final_block, package_key.begin(), cipher->BLOCK_SIZE);
    }
 
-void unpackage(BlockCipher* cipher,
-               const byte input[], u32bit input_len,
-               byte output[])
+void aont_unpackage(BlockCipher* cipher,
+                    const byte input[], u32bit input_len,
+                    byte output[])
    {
    if(!cipher->valid_keylength(cipher->BLOCK_SIZE))
       throw Invalid_Argument("AONT::unpackage: Invalid cipher");
@@ -116,5 +114,3 @@ void unpackage(BlockCipher* cipher,
    }
 
 }
-
-}
diff --git a/src/constructs/aont/package.h b/src/constructs/aont/package.h
index 9c23d1836..211623347 100644
--- a/src/constructs/aont/package.h
+++ b/src/constructs/aont/package.h
@@ -14,8 +14,6 @@
 
 namespace Botan {
 
-namespace AllOrNothingTransform {
-
 /**
 * Rivest's Package Tranform
 * @arg rng the random number generator to use
@@ -25,10 +23,10 @@ namespace AllOrNothingTransform {
 * @arg output the output data buffer (must be at least
 *      input_len + cipher->BLOCK_SIZE bytes long)
 */
-void BOTAN_DLL package(RandomNumberGenerator& rng,
-                       BlockCipher* cipher,
-                       const byte input[], u32bit input_len,
-                       byte output[]);
+void BOTAN_DLL aont_package(RandomNumberGenerator& rng,
+                            BlockCipher* cipher,
+                            const byte input[], u32bit input_len,
+                            byte output[]);
 
 /**
 * Rivest's Package Tranform (Inversion)
@@ -39,11 +37,9 @@ void BOTAN_DLL package(RandomNumberGenerator& rng,
 * @arg output the output data buffer (must be at least
 *      input_len - cipher->BLOCK_SIZE bytes long)
 */
-void BOTAN_DLL unpackage(BlockCipher* cipher,
-                         const byte input[], u32bit input_len,
-                         byte output[]);
-
-}
+void BOTAN_DLL aont_unpackage(BlockCipher* cipher,
+                              const byte input[], u32bit input_len,
+                              byte output[]);
 
 }
 
diff --git a/src/constructs/cryptobox/cryptobox.cpp b/src/constructs/cryptobox/cryptobox.cpp
index 371b52e66..7d27c0523 100644
--- a/src/constructs/cryptobox/cryptobox.cpp
+++ b/src/constructs/cryptobox/cryptobox.cpp
@@ -18,8 +18,6 @@
 
 namespace Botan {
 
-namespace CryptoBox {
-
 namespace {
 
 /*
@@ -40,9 +38,9 @@ const u32bit PBKDF_OUTPUT_LEN = CIPHER_KEY_LEN + CIPHER_IV_LEN + MAC_KEY_LEN;
 
 }
 
-std::string encrypt(const byte input[], u32bit input_len,
-                    const std::string& passphrase,
-                    RandomNumberGenerator& rng)
+std::string cryptobox_encrypt(const byte input[], u32bit input_len,
+                              const std::string& passphrase,
+                              RandomNumberGenerator& rng)
    {
    SecureVector<byte> pbkdf_salt(PBKDF_SALT_LEN);
    rng.randomize(pbkdf_salt.begin(), pbkdf_salt.size());
@@ -91,8 +89,8 @@ std::string encrypt(const byte input[], u32bit input_len,
                            "BOTAN CRYPTOBOX MESSAGE");
    }
 
-std::string decrypt(const byte input[], u32bit input_len,
-                    const std::string& passphrase)
+std::string cryptobox_decrypt(const byte input[], u32bit input_len,
+                              const std::string& passphrase)
    {
    DataSource_Memory input_src(input, input_len);
    SecureVector<byte> ciphertext =
@@ -120,7 +118,7 @@ std::string decrypt(const byte input[], u32bit input_len,
                            CIPHER_IV_LEN);
 
    Pipe pipe(new Fork(
-                get_cipher("Serpent/CTR-BE", cipher_key, iv, ENCRYPTION),
+                get_cipher("Serpent/CTR-BE", cipher_key, iv, DECRYPTION),
                 new MAC_Filter(new HMAC(new SHA_512),
                                mac_key, MAC_OUTPUT_LEN)));
 
@@ -141,5 +139,3 @@ std::string decrypt(const byte input[], u32bit input_len,
    }
 
 }
-
-}
diff --git a/src/constructs/cryptobox/cryptobox.h b/src/constructs/cryptobox/cryptobox.h
index a30cb244a..3dbb894ba 100644
--- a/src/constructs/cryptobox/cryptobox.h
+++ b/src/constructs/cryptobox/cryptobox.h
@@ -13,8 +13,6 @@
 
 namespace Botan {
 
-namespace CryptoBox {
-
 /**
 * Encrypt a message
 * @param input the input data
@@ -22,9 +20,9 @@ namespace CryptoBox {
 * @param passphrase the passphrase used to encrypt the message
 * @param rng a ref to a random number generator, such as AutoSeeded_RNG
 */
-BOTAN_DLL std::string encrypt(const byte input[], u32bit input_len,
-                              const std::string& passphrase,
-                              RandomNumberGenerator& rng);
+BOTAN_DLL std::string cryptobox_encrypt(const byte input[], u32bit input_len,
+                                        const std::string& passphrase,
+                                        RandomNumberGenerator& rng);
 
 /**
 * Decrypt a message encrypted with CryptoBox::encrypt
@@ -32,10 +30,8 @@ BOTAN_DLL std::string encrypt(const byte input[], u32bit input_len,
 * @param input_len the length of input in bytes
 * @param passphrase the passphrase used to encrypt the message
 */
-BOTAN_DLL std::string decrypt(const byte input[], u32bit input_len,
-                              const std::string& passphrase);
-
-}
+BOTAN_DLL std::string cryptobox_decrypt(const byte input[], u32bit input_len,
+                                        const std::string& passphrase);
 
 }
 
diff --git a/src/constructs/passhash/passhash9.h b/src/constructs/passhash/passhash9.h
index 6020dce42..8900d55d3 100644
--- a/src/constructs/passhash/passhash9.h
+++ b/src/constructs/passhash/passhash9.h
@@ -16,7 +16,7 @@ namespace Botan {
 * Create a password hash using PBKDF2
 * @param password the password
 * @param rng a random number generator
-* @Param work_factor how much work to do to slow down guessing attacks
+* @param work_factor how much work to do to slow down guessing attacks
 */
 std::string BOTAN_DLL generate_passhash9(const std::string& password,
                                          RandomNumberGenerator& rng,
diff --git a/src/constructs/tss/tss.h b/src/constructs/tss/tss.h
index c8b0242d8..485e42c53 100644
--- a/src/constructs/tss/tss.h
+++ b/src/constructs/tss/tss.h
@@ -15,16 +15,19 @@
 
 namespace Botan {
 
+/**
+* A split secret, using the format from draft-mcgrew-tss-03
+*/
 class BOTAN_DLL RTSS_Share
    {
    public:
       /**
-      * @arg M the number of shares needed to reconstruct
-      * @arg N the number of shares generated
-      * @arg secret the secret to split
-      * @arg secret_len the length of the secret
-      * @arg identifier the 16 byte share identifier
-      * @arg rng the random number generator to use
+      * @param M the number of shares needed to reconstruct
+      * @param N the number of shares generated
+      * @param secret the secret to split
+      * @param secret_len the length of the secret
+      * @param identifier the 16 byte share identifier
+      * @param rng the random number generator to use
       */
       static std::vector<RTSS_Share>
          split(byte M, byte N,
@@ -33,18 +36,36 @@ class BOTAN_DLL RTSS_Share
                RandomNumberGenerator& rng);
 
       /**
-      * @arg shares the list of shares
+      * @param shares the list of shares
       */
       static SecureVector<byte>
         reconstruct(const std::vector<RTSS_Share>& shares);
 
       RTSS_Share() {}
-      RTSS_Share(const std::string&);
 
+      /**
+      * @param hex_input the share encoded in hexadecimal
+      */
+      RTSS_Share(const std::string& hex_input);
+
+      /**
+      * @return hex representation
+      */
       std::string to_string() const;
+
+      /**
+      * @return share identifier
+      */
       byte share_id() const;
 
+      /**
+      * @return size of this share in bytes
+      */
       u32bit size() const { return contents.size(); }
+
+      /**
+      * @return if this TSS share was initialized or not
+      */
       bool initialized() const { return (contents.size() > 0); }
    private:
       SecureVector<byte> contents;
diff --git a/src/engine/aes_isa_eng/aes_isa_engine.h b/src/engine/aes_isa_eng/aes_isa_engine.h
index 5f22e4105..3c4d3e936 100644
--- a/src/engine/aes_isa_eng/aes_isa_engine.h
+++ b/src/engine/aes_isa_eng/aes_isa_engine.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Engine for AES instructions
 * (C) 2009 Jack Lloyd
 *
@@ -12,11 +12,15 @@
 
 namespace Botan {
 
+/**
+* Engine for implementations that hook into CPU-specific
+* AES implementations (eg AES-NI, VIA C7, or AMD Geode)
+*/
 class AES_ISA_Engine : public Engine
    {
    public:
       std::string provider_name() const { return "aes_isa"; }
-   private:
+
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) const;
    };
diff --git a/src/engine/amd64_eng/amd64_engine.cpp b/src/engine/amd64_eng/amd64_engine.cpp
index 6de1484fb..262bd5809 100644
--- a/src/engine/amd64_eng/amd64_engine.cpp
+++ b/src/engine/amd64_eng/amd64_engine.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * AMD64 Assembly Implementation Engine
 * (C) 1999-2008 Jack Lloyd
 *
diff --git a/src/engine/amd64_eng/amd64_engine.h b/src/engine/amd64_eng/amd64_engine.h
index dc6f3e993..dc3d4cefc 100644
--- a/src/engine/amd64_eng/amd64_engine.h
+++ b/src/engine/amd64_eng/amd64_engine.h
@@ -1,4 +1,4 @@
-/**
+/*
 * x86-64 Assembly Implementation Engines
 * (C) 1999-2008 Jack Lloyd
 *
@@ -12,11 +12,14 @@
 
 namespace Botan {
 
+/**
+* Engine for implementations that are x86-64 specific
+*/
 class AMD64_Assembler_Engine : public Engine
    {
    public:
       std::string provider_name() const { return "amd64"; }
-   private:
+
       HashFunction* find_hash(const SCAN_Name& reqeust,
                               Algorithm_Factory&) const;
    };
diff --git a/src/engine/def_engine/default_engine.h b/src/engine/def_engine/default_engine.h
index 1e40cfe46..f7e6d9746 100644
--- a/src/engine/def_engine/default_engine.h
+++ b/src/engine/def_engine/default_engine.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Default Engine
 */
 class Default_Engine : public Engine
@@ -35,12 +35,9 @@ class Default_Engine : public Engine
       Modular_Exponentiator* mod_exp(const BigInt& n,
                                      Power_Mod::Usage_Hints) const;
 
-      virtual bool can_add_algorithms() { return true; }
-
       Keyed_Filter* get_cipher(const std::string&, Cipher_Dir,
                                Algorithm_Factory&);
 
-   private:
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) const;
 
diff --git a/src/engine/def_engine/lookup_hash.cpp b/src/engine/def_engine/lookup_hash.cpp
index 1d96d4f3f..47c6c0a56 100644
--- a/src/engine/def_engine/lookup_hash.cpp
+++ b/src/engine/def_engine/lookup_hash.cpp
@@ -26,10 +26,6 @@
   #include <botan/bmw_512.h>
 #endif
 
-#if defined(BOTAN_HAS_FORK_256)
-  #include <botan/fork256.h>
-#endif
-
 #if defined(BOTAN_HAS_GOST_34_11)
   #include <botan/gost_3411.h>
 #endif
@@ -116,11 +112,6 @@ Default_Engine::find_hash(const SCAN_Name& request,
       return new BMW_512;
 #endif
 
-#if defined(BOTAN_HAS_FORK_256)
-   if(request.algo_name() == "FORK-256")
-      return new FORK_256;
-#endif
-
 #if defined(BOTAN_HAS_GOST_34_11)
    if(request.algo_name() == "GOST-34.11")
       return new GOST_34_11;
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 69592886c..c9bcd6126 100644
--- a/src/engine/engine.h
+++ b/src/engine/engine.h
@@ -26,67 +26,117 @@ namespace Botan {
 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
    {
    public:
       virtual ~Engine() {}
 
+      /**
+      * @return name of this engine
+      */
       virtual std::string provider_name() const = 0;
 
-      // Lookup functions
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual BlockCipher*
-         find_block_cipher(const SCAN_Name&, Algorithm_Factory&) const
-         { return 0; }
-
+         find_block_cipher(const SCAN_Name& algo_spec,
+                           Algorithm_Factory& af) const;
+
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual StreamCipher*
-         find_stream_cipher(const SCAN_Name&, Algorithm_Factory&) const
-         { return 0; }
-
+         find_stream_cipher(const SCAN_Name& algo_spec,
+                            Algorithm_Factory& af) const;
+
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual HashFunction*
-         find_hash(const SCAN_Name&, Algorithm_Factory&) const
-         { return 0; }
-
+         find_hash(const SCAN_Name& algo_spec,
+                   Algorithm_Factory& af) const;
+
+      /**
+      * @param algo_spec the algorithm name/specification
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
       virtual MessageAuthenticationCode*
-         find_mac(const SCAN_Name&, Algorithm_Factory&) const
-         { return 0; }
-
+         find_mac(const SCAN_Name& algo_spec,
+                  Algorithm_Factory& af) const;
+
+      /**
+      * @param n the modulus
+      * @param hints any use hints
+      * @return newly allocated object, or NULL
+      */
       virtual Modular_Exponentiator*
-         mod_exp(const BigInt&, Power_Mod::Usage_Hints) const
-         { return 0; }
-
-      virtual Keyed_Filter* get_cipher(const std::string&,
-                                       Cipher_Dir,
-                                       Algorithm_Factory&)
-         { return 0; }
-
+         mod_exp(const BigInt& n,
+                 Power_Mod::Usage_Hints hints) const;
+
+      /**
+      * Return a new cipher object
+      * @param algo_spec the algorithm name/specification
+      * @param dir specifies if encryption or decryption is desired
+      * @param af an algorithm factory object
+      * @return newly allocated object, or NULL
+      */
+      virtual Keyed_Filter* get_cipher(const std::string& algo_spec,
+                                       Cipher_Dir dir,
+                                       Algorithm_Factory& af);
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
       virtual PK_Ops::Key_Agreement*
-         get_key_agreement_op(const Private_Key&) const
-         {
-         return 0;
-         }
-
-      virtual PK_Ops::Signature* get_signature_op(const Private_Key&) const
-         {
-         return 0;
-         }
-
-      virtual PK_Ops::Verification* get_verify_op(const Public_Key&) const
-         {
-         return 0;
-         }
-
-      virtual PK_Ops::Encryption* get_encryption_op(const Public_Key&) const
-         {
-         return 0;
-         }
-
-      virtual PK_Ops::Decryption* get_decryption_op(const Private_Key&) const
-         {
-         return 0;
-         }
+         get_key_agreement_op(const Private_Key& key) const;
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Signature*
+         get_signature_op(const Private_Key& key) const;
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Verification*
+         get_verify_op(const Public_Key& key) const;
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Encryption*
+         get_encryption_op(const Public_Key& key) const;
+
+      /**
+      * Return a new operator object for this key, if possible
+      * @param key the key we want an operator for
+      * @return newly allocated operator object, or NULL
+      */
+      virtual PK_Ops::Decryption*
+         get_decryption_op(const Private_Key& key) const;
    };
 
 }
diff --git a/src/engine/gnump/gmp_wrap.h b/src/engine/gnump/gmp_wrap.h
index 82437ceba..52d130d6b 100644
--- a/src/engine/gnump/gmp_wrap.h
+++ b/src/engine/gnump/gmp_wrap.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* Lightweight GMP mpz_t Wrapper
+/**
+* Lightweight GMP mpz_t wrapper. For internal use only.
 */
 class GMP_MPZ
    {
diff --git a/src/engine/gnump/gnump_engine.h b/src/engine/gnump/gnump_engine.h
index 1ca5a3548..fe154b914 100644
--- a/src/engine/gnump/gnump_engine.h
+++ b/src/engine/gnump/gnump_engine.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* GMP Engine
+/**
+* Engine using GNU MP
 */
 class GMP_Engine : public Engine
    {
diff --git a/src/engine/ia32_eng/ia32_engine.h b/src/engine/ia32_eng/ia32_engine.h
index 517b88aa8..6e0a8a5f4 100644
--- a/src/engine/ia32_eng/ia32_engine.h
+++ b/src/engine/ia32_eng/ia32_engine.h
@@ -1,4 +1,4 @@
-/**
+/*
 * IA-32 Assembly Implementation Engines
 * (C) 1999-2008 Jack Lloyd
 *
@@ -12,11 +12,14 @@
 
 namespace Botan {
 
+/**
+* Engine for x86-32 specific implementations
+*/
 class IA32_Assembler_Engine : public Engine
    {
    public:
       std::string provider_name() const { return "ia32"; }
-   private:
+
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) 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/engine/openssl/bn_wrap.h b/src/engine/openssl/bn_wrap.h
index 02a229fdd..372f5a329 100644
--- a/src/engine/openssl/bn_wrap.h
+++ b/src/engine/openssl/bn_wrap.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* Lightweight OpenSSL BN Wrapper
+/**
+* Lightweight OpenSSL BN wrapper. For internal use only.
 */
 class OSSL_BN
    {
@@ -36,8 +36,8 @@ class OSSL_BN
       ~OSSL_BN();
    };
 
-/*
-* Lightweight OpenSSL BN_CTX Wrapper
+/**
+* Lightweight OpenSSL BN_CTX wrapper. For internal use only.
 */
 class OSSL_BN_CTX
    {
diff --git a/src/engine/openssl/openssl_engine.h b/src/engine/openssl/openssl_engine.h
index 1ee7e4c11..b1f71a160 100644
--- a/src/engine/openssl/openssl_engine.h
+++ b/src/engine/openssl/openssl_engine.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * OpenSSL Engine
 */
 class OpenSSL_Engine : public Engine
@@ -37,7 +37,7 @@ class OpenSSL_Engine : public Engine
 
       Modular_Exponentiator* mod_exp(const BigInt&,
                                      Power_Mod::Usage_Hints) const;
-   private:
+
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) const;
 
diff --git a/src/engine/simd_engine/simd_engine.cpp b/src/engine/simd_engine/simd_engine.cpp
index e889ca161..aa434d669 100644
--- a/src/engine/simd_engine/simd_engine.cpp
+++ b/src/engine/simd_engine/simd_engine.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * SIMD Engine
 * (C) 1999-2009 Jack Lloyd
 *
diff --git a/src/engine/simd_engine/simd_engine.h b/src/engine/simd_engine/simd_engine.h
index 722b5529b..73f7d2233 100644
--- a/src/engine/simd_engine/simd_engine.h
+++ b/src/engine/simd_engine/simd_engine.h
@@ -1,4 +1,4 @@
-/**
+/*
 * SIMD Assembly Engine
 * (C) 1999-2009 Jack Lloyd
 *
@@ -12,11 +12,14 @@
 
 namespace Botan {
 
+/**
+* Engine for implementations that use some kind of SIMD
+*/
 class SIMD_Engine : public Engine
    {
    public:
       std::string provider_name() const { return "simd"; }
-   private:
+
       BlockCipher* find_block_cipher(const SCAN_Name&,
                                      Algorithm_Factory&) const;
 
diff --git a/src/entropy/beos_stats/es_beos.cpp b/src/entropy/beos_stats/es_beos.cpp
index 148d38b9b..2b4a7a24f 100644
--- a/src/entropy/beos_stats/es_beos.cpp
+++ b/src/entropy/beos_stats/es_beos.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * BeOS EntropySource
 * (C) 1999-2008 Jack Lloyd
 *
diff --git a/src/entropy/beos_stats/es_beos.h b/src/entropy/beos_stats/es_beos.h
index be80ad340..31029a88c 100644
--- a/src/entropy/beos_stats/es_beos.h
+++ b/src/entropy/beos_stats/es_beos.h
@@ -1,4 +1,4 @@
-/**
+/*
 * BeOS EntropySource
 * (C) 1999-2008 Jack Lloyd
 *
diff --git a/src/entropy/dev_random/dev_random.h b/src/entropy/dev_random/dev_random.h
index 3ffe536e3..e20e74300 100644
--- a/src/entropy/dev_random/dev_random.h
+++ b/src/entropy/dev_random/dev_random.h
@@ -14,6 +14,9 @@
 
 namespace Botan {
 
+/**
+* Entropy source reading from kernel devices like /dev/random
+*/
 class Device_EntropySource : public EntropySource
    {
    public:
diff --git a/src/entropy/egd/es_egd.cpp b/src/entropy/egd/es_egd.cpp
index bd8dc8590..29880a544 100644
--- a/src/entropy/egd/es_egd.cpp
+++ b/src/entropy/egd/es_egd.cpp
@@ -46,7 +46,7 @@ int EGD_EntropySource::EGD_Socket::open_socket(const std::string& path)
       if(sizeof(addr.sun_path) < path.length() + 1)
          throw std::invalid_argument("EGD socket path is too long");
 
-      std::strcpy(addr.sun_path, path.c_str());
+      std::strncpy(addr.sun_path, path.c_str(), sizeof(addr.sun_path));
 
       int len = sizeof(addr.sun_family) + std::strlen(addr.sun_path) + 1;
 
diff --git a/src/entropy/egd/es_egd.h b/src/entropy/egd/es_egd.h
index 1a3618989..defe88a54 100644
--- a/src/entropy/egd/es_egd.h
+++ b/src/entropy/egd/es_egd.h
@@ -1,4 +1,4 @@
-/**
+/*
 * EGD EntropySource
 * (C) 1999-2007 Jack Lloyd
 *
diff --git a/src/entropy/entropy_src.h b/src/entropy/entropy_src.h
index 4d01bce7c..fa61d9ea8 100644
--- a/src/entropy/entropy_src.h
+++ b/src/entropy/entropy_src.h
@@ -1,4 +1,4 @@
-/**
+/*
 * EntropySource
 * (C) 2008-2009 Jack Lloyd
 *
@@ -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)
          {
@@ -63,9 +93,16 @@ class BOTAN_DLL Entropy_Accumulator
       double collected_bits;
    };
 
+/**
+* Entropy accumulator that puts the input into a BufferedComputation
+*/
 class BOTAN_DLL Entropy_Accumulator_BufferedComputation : public Entropy_Accumulator
    {
    public:
+      /**
+      * @param sink the hash or MAC we are feeding the poll data into
+      * @param goal is how many bits we want to collect in this poll
+      */
       Entropy_Accumulator_BufferedComputation(BufferedComputation& sink,
                                               u32bit goal) :
          Entropy_Accumulator(goal), entropy_sink(sink) {}
@@ -85,8 +122,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/entropy/hres_timer/hres_timer.h b/src/entropy/hres_timer/hres_timer.h
index a602d5d7b..c693b8d4e 100644
--- a/src/entropy/hres_timer/hres_timer.h
+++ b/src/entropy/hres_timer/hres_timer.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* High Resolution Timestamp Source
+/**
+* Entropy source using high resolution timers
 */
 class High_Resolution_Timestamp : public EntropySource
    {
diff --git a/src/entropy/proc_walk/es_ftw.cpp b/src/entropy/proc_walk/es_ftw.cpp
index 5e2b17860..53e39d834 100644
--- a/src/entropy/proc_walk/es_ftw.cpp
+++ b/src/entropy/proc_walk/es_ftw.cpp
@@ -22,9 +22,23 @@
 
 namespace Botan {
 
+/**
+* Returns file descriptors. Until it doesn't
+*/
+class File_Descriptor_Source
+   {
+   public:
+      /**
+      * @return next file descriptor, or -1 if done
+      */
+      virtual int next_fd() = 0;
+
+      virtual ~File_Descriptor_Source() {}
+   };
+
 namespace {
 
-class Directory_Walker : public FTW_EntropySource::File_Descriptor_Source
+class Directory_Walker : public File_Descriptor_Source
    {
    public:
       Directory_Walker(const std::string& root) { add_directory(root); }
diff --git a/src/entropy/proc_walk/es_ftw.h b/src/entropy/proc_walk/es_ftw.h
index d7a719818..3ba222d46 100644
--- a/src/entropy/proc_walk/es_ftw.h
+++ b/src/entropy/proc_walk/es_ftw.h
@@ -24,17 +24,9 @@ class FTW_EntropySource : public EntropySource
 
       FTW_EntropySource(const std::string& root_dir);
       ~FTW_EntropySource();
-
-      class File_Descriptor_Source
-         {
-         public:
-            virtual int next_fd() = 0;
-            virtual ~File_Descriptor_Source() {}
-         };
    private:
-
       std::string path;
-      File_Descriptor_Source* dir;
+      class File_Descriptor_Source* dir;
    };
 
 }
diff --git a/src/entropy/unix_procs/unix_cmd.cpp b/src/entropy/unix_procs/unix_cmd.cpp
index 34e7c314a..c92c84b4c 100644
--- a/src/entropy/unix_procs/unix_cmd.cpp
+++ b/src/entropy/unix_procs/unix_cmd.cpp
@@ -37,6 +37,7 @@ void do_exec(const std::vector<std::string>& arg_list,
       {
       const std::string full_path = paths[j] + "/" + arg_list[0];
       const char* fsname = full_path.c_str();
+
       ::execl(fsname, fsname, arg1, arg2, arg3, arg4, NULL);
       }
    }
@@ -50,7 +51,9 @@ struct pipe_wrapper
    {
    int fd;
    pid_t pid;
-   pipe_wrapper() { fd = -1; pid = 0; }
+
+   pipe_wrapper(int f, pid_t p) : fd(f), pid(p) {}
+   ~pipe_wrapper() { ::close(fd); }
    };
 
 /**
@@ -152,9 +155,7 @@ void DataSource_Command::create_pipe(const std::vector<std::string>& paths)
       }
    else if(pid > 0)
       {
-      pipe = new pipe_wrapper;
-      pipe->fd = pipe_fd[0];
-      pipe->pid = pid;
+      pipe = new pipe_wrapper(pipe_fd[0], pid);
       ::close(pipe_fd[1]);
       }
    else
@@ -200,7 +201,6 @@ void DataSource_Command::shutdown_pipe()
             }
          }
 
-      ::close(pipe->fd);
       delete pipe;
       pipe = 0;
       }
diff --git a/src/entropy/unix_procs/unix_cmd.h b/src/entropy/unix_procs/unix_cmd.h
index 7decf587f..3abca8f37 100644
--- a/src/entropy/unix_procs/unix_cmd.h
+++ b/src/entropy/unix_procs/unix_cmd.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Unix Command Execution
 * (C) 1999-2007 Jack Lloyd
 *
@@ -20,6 +20,10 @@ namespace Botan {
 */
 struct Unix_Program
    {
+   /**
+   * @param n is the name and arguments of what we are going run
+   * @param p is the priority level (lower prio numbers get polled first)
+   */
    Unix_Program(const char* n, u32bit p)
       { name_and_args = n; priority = p; working = true; }
 
diff --git a/src/entropy/win32_stats/es_win32.cpp b/src/entropy/win32_stats/es_win32.cpp
index e9f564fee..b3d7d27e5 100644
--- a/src/entropy/win32_stats/es_win32.cpp
+++ b/src/entropy/win32_stats/es_win32.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Win32 EntropySource
 * (C) 1999-2009 Jack Lloyd
 *
diff --git a/src/entropy/win32_stats/es_win32.h b/src/entropy/win32_stats/es_win32.h
index 0aa9054e3..2e46c773d 100644
--- a/src/entropy/win32_stats/es_win32.h
+++ b/src/entropy/win32_stats/es_win32.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Win32 EntropySource
 * (C) 1999-2009 Jack Lloyd
 *
diff --git a/src/filters/basefilt.cpp b/src/filters/basefilt.cpp
index c91a5aa62..124c0a887 100644
--- a/src/filters/basefilt.cpp
+++ b/src/filters/basefilt.cpp
@@ -6,9 +6,15 @@
 */
 
 #include <botan/basefilt.h>
+#include <botan/key_filt.h>
 
 namespace Botan {
 
+void Keyed_Filter::set_iv(const InitializationVector&)
+   {
+   // assert that the iv is empty?
+   }
+
 /*
 * Chain Constructor
 */
diff --git a/src/filters/buf_filt.h b/src/filters/buf_filt.h
index 582f585b0..1ab402df7 100644
--- a/src/filters/buf_filt.h
+++ b/src/filters/buf_filt.h
@@ -12,6 +12,10 @@
 
 namespace Botan {
 
+/**
+* Filter mixin that breaks input into blocks, useful for
+* cipher modes
+*/
 class BOTAN_DLL Buffered_Filter
    {
    public:
diff --git a/src/filters/bzip2/bzip2.cpp b/src/filters/bzip2/bzip2.cpp
index 9dcee8fdf..b4b04a13e 100644
--- a/src/filters/bzip2/bzip2.cpp
+++ b/src/filters/bzip2/bzip2.cpp
@@ -54,8 +54,6 @@ void bzip_free(void* info_ptr, void* ptr)
    info->alloc->deallocate(ptr, i->second);
    }
 
-}
-
 /*
 * Wrapper Type for Bzip2 Stream
 */
@@ -79,6 +77,8 @@ class Bzip_Stream
          }
    };
 
+}
+
 /*
 * Bzip_Compression Constructor
 */
diff --git a/src/filters/bzip2/bzip2.h b/src/filters/bzip2/bzip2.h
index f42263537..3b40dbe40 100644
--- a/src/filters/bzip2/bzip2.h
+++ b/src/filters/bzip2/bzip2.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Bzip Compression Filter
 */
 class BOTAN_DLL Bzip_Compression : public Filter
@@ -35,7 +35,7 @@ class BOTAN_DLL Bzip_Compression : public Filter
       class Bzip_Stream* bz;
    };
 
-/*
+/**
 * Bzip Decompression Filter
 */
 class BOTAN_DLL Bzip_Decompression : public Filter
diff --git a/src/filters/data_snk.h b/src/filters/data_snk.h
index fda06e492..57020e9dd 100644
--- a/src/filters/data_snk.h
+++ b/src/filters/data_snk.h
@@ -45,11 +45,11 @@ class BOTAN_DLL DataSink_Stream : public DataSink
 
       /**
       * Construct a DataSink_Stream from a stream.
-      * @param file the name of the file to open a stream to
+      * @param pathname the name of the file to open a stream to
       * @param use_binary indicates whether to treat the file
       * as a binary file or not
       */
-      DataSink_Stream(const std::string& filename,
+      DataSink_Stream(const std::string& pathname,
                       bool use_binary = false);
 
       ~DataSink_Stream();
diff --git a/src/filters/data_src.h b/src/filters/data_src.h
index dea46584c..016402b61 100644
--- a/src/filters/data_src.h
+++ b/src/filters/data_src.h
@@ -21,22 +21,25 @@ class BOTAN_DLL DataSource
    {
    public:
       /**
-      * Read from the source. Moves the internal offset so that
-      * every call to read will return a new portion of the source.
+      * Read from the source. Moves the internal offset so that every
+      * call to read will return a new portion of the source.
+      *
       * @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;
 
       /**
-      * Read from the source but do not modify the internal offset. Consecutive
-      * calls to peek() will return portions of the source starting at the same
-      * position.
+      * Read from the source but do not modify the internal
+      * offset. Consecutive calls to peek() will return portions of
+      * the source starting at the same position.
+      *
       * @param out the byte array to write the output to
       * @param length the length of the byte array out
-      * @return the length in bytes that was actually read and put
+      * @param peek_offset the offset into the stream to read at
+      * @return length in bytes that was actually read and put
       * into out
       */
       virtual u32bit peek(byte out[], u32bit length,
@@ -49,22 +52,22 @@ class BOTAN_DLL DataSource
       virtual bool end_of_data() const = 0;
       /**
       * return the id of this data source
-      * @return the std::string representing the id of this data source
+      * @return std::string representing the id of this data source
       */
       virtual std::string id() const { return ""; }
 
       /**
       * Read one byte.
-      * @param the byte to read to
-      * @return the length in bytes that was actually read and put
+      * @param out the byte to read to
+      * @return length in bytes that was actually read and put
       * into out
       */
       u32bit read_byte(byte& out);
 
       /**
       * Peek at one byte.
-      * @param the byte to read to
-      * @return the length in bytes that was actually read and put
+      * @param out an output byte
+      * @return length in bytes that was actually read and put
       * into out
       */
       u32bit peek_byte(byte& out) const;
@@ -72,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/filter.h b/src/filters/filter.h
index 8fc114db7..55274beae 100644
--- a/src/filters/filter.h
+++ b/src/filters/filter.h
@@ -31,12 +31,13 @@ class BOTAN_DLL Filter
 
       /**
       * Start a new message. Must be closed by end_msg() before another
-      * message can be startet.
+      * message can be started.
       */
       virtual void start_msg() {}
 
       /**
-      * Tell the Filter that the current message shall be ended.
+      * Notify that the current message is finished; flush buffers and
+      * do end-of-message processing (if any).
       */
       virtual void end_msg() {}
 
@@ -46,6 +47,28 @@ class BOTAN_DLL Filter
       */
       virtual bool attachable() { return true; }
 
+      virtual ~Filter() {}
+   protected:
+      /**
+      * @param in some input for the filter
+      * @param length the length of in
+      */
+      void send(const byte in[], u32bit length);
+
+      /**
+      * @param in some input for the filter
+      */
+      void send(byte in) { send(&in, 1); }
+
+      /**
+      * @param in some input for the filter
+      */
+      void send(const MemoryRegion<byte>& in) { send(in.begin(), in.size()); }
+      Filter();
+   private:
+      Filter(const Filter&) {}
+      Filter& operator=(const Filter&) { return (*this); }
+
       /**
       * Start a new message in *this and all following filters. Only for
       * internal use, not intended for use in client applications.
@@ -61,21 +84,28 @@ class BOTAN_DLL Filter
       Filter(const Filter&) = delete;
       Filter& operator=(const Filter&) = delete;
 
-      virtual ~Filter() {}
-   protected:
-      void send(const byte[], u32bit);
-      void send(byte input) { send(&input, 1); }
-      void send(const MemoryRegion<byte>& in) { send(in.begin(), in.size()); }
-      Filter();
-   private:
       u32bit total_ports() const;
       u32bit current_port() const { return port_num; }
-      void set_port(u32bit);
+
+      /**
+      * Set the active port
+      * @param new_port the new value
+      */
+      void set_port(u32bit new_port);
 
       u32bit owns() const { return filter_owns; }
 
-      void attach(Filter*);
-      void set_next(Filter*[], u32bit);
+      /**
+      * Attach another filter to this one
+      * @param f filter to attach
+      */
+      void attach(Filter* f);
+
+      /**
+      * @param filters the filters to set
+      * @param count number of items in filters
+      */
+      void set_next(Filter* filters[], u32bit count);
       Filter* get_next() const;
 
       SecureVector<byte> write_queue;
@@ -92,10 +122,15 @@ class BOTAN_DLL Filter
 class BOTAN_DLL Fanout_Filter : public Filter
    {
    protected:
+      /**
+      * Increment the number of filters past us that we own
+      */
       void incr_owns() { ++filter_owns; }
 
       void set_port(u32bit n) { Filter::set_port(n); }
+
       void set_next(Filter* f[], u32bit n) { Filter::set_next(f, n); }
+
       void attach(Filter* f) { Filter::attach(f); }
    };
 
diff --git a/src/filters/filters.h b/src/filters/filters.h
index 208332a56..5953518d3 100644
--- a/src/filters/filters.h
+++ b/src/filters/filters.h
@@ -44,7 +44,7 @@ class BOTAN_DLL StreamCipher_Filter : public Keyed_Filter
       */
       void write(const byte input[], u32bit input_len);
 
-      bool valid_iv_length(u32bit iv_len)
+      bool valid_iv_length(u32bit iv_len) const
          { return cipher->valid_iv_length(iv_len); }
 
       /**
@@ -160,8 +160,8 @@ class BOTAN_DLL MAC_Filter : public Keyed_Filter
 
       /**
       * Construct a MAC filter. The MAC key will be left empty.
-      * @param mac the MAC to use
-      * @param len the output length of this filter. Leave the default
+      * @param mac_obj the MAC to use
+      * @param out_len the output length of this filter. Leave the default
       * value 0 if you want to use the full output of the
       * MAC. Otherwise, specify a smaller value here so that the
       * output of the MAC will be cut off.
@@ -174,9 +174,9 @@ class BOTAN_DLL MAC_Filter : public Keyed_Filter
 
       /**
       * Construct a MAC filter.
-      * @param mac the MAC to use
+      * @param mac_obj the MAC to use
       * @param key the MAC key to use
-      * @param len the output length of this filter. Leave the default
+      * @param out_len the output length of this filter. Leave the default
       * value 0 if you want to use the full output of the
       * MAC. Otherwise, specify a smaller value here so that the
       * output of the MAC will be cut off.
diff --git a/src/filters/key_filt.h b/src/filters/key_filt.h
index 36af91f88..0afea446c 100644
--- a/src/filters/key_filt.h
+++ b/src/filters/key_filt.h
@@ -21,23 +21,32 @@ class BOTAN_DLL Keyed_Filter : public Filter
    {
    public:
       /**
-      * Set the key of this filter.
-      * @param key the key to set
+      * Set the key of this filter
+      * @param key the key to use
       */
       virtual void set_key(const SymmetricKey& key) = 0;
 
       /**
-      * Set the initialization vector of this filter.
-      * @param iv the initialization vector to set
+      * Set the initialization vector of this filter. Note: you should
+      * call set_iv() only after you have called set_key()
+      * @param iv the initialization vector to use
       */
-      virtual void set_iv(const InitializationVector&) {}
+      virtual void set_iv(const InitializationVector& iv);
 
       /**
-      * Check whether a key length is valid for this filter.
+      * Check whether a key length is valid for this filter
       * @param length the key length to be checked for validity
       * @return true if the key length is valid, false otherwise
       */
       virtual bool valid_keylength(u32bit length) const = 0;
+
+      /**
+      * Check whether an IV length is valid for this filter
+      * @param length the IV length to be checked for validity
+      * @return true if the IV length is valid, false otherwise
+      */
+      virtual bool valid_iv_length(u32bit length) const
+         { return (length == 0); }
    };
 
 }
diff --git a/src/filters/modes/cbc/cbc.cpp b/src/filters/modes/cbc/cbc.cpp
index 4f484da77..b0c3493e7 100644
--- a/src/filters/modes/cbc/cbc.cpp
+++ b/src/filters/modes/cbc/cbc.cpp
@@ -49,7 +49,7 @@ CBC_Encryption::CBC_Encryption(BlockCipher* ciph,
 */
 void CBC_Encryption::set_iv(const InitializationVector& iv)
    {
-   if(iv.length() != state.size())
+   if(!valid_iv_length(iv.length()))
       throw Invalid_IV_Length(name(), iv.length());
 
    state = iv.bits_of();
@@ -114,8 +114,7 @@ std::string CBC_Encryption::name() const
 */
 CBC_Decryption::CBC_Decryption(BlockCipher* ciph,
                                BlockCipherModePaddingMethod* pad) :
-   Buffered_Filter(ciph->parallelism() * ciph->BLOCK_SIZE,
-                   ciph->BLOCK_SIZE),
+   Buffered_Filter(ciph->parallel_bytes(), ciph->BLOCK_SIZE),
    cipher(ciph), padder(pad)
    {
    if(!padder->valid_blocksize(cipher->BLOCK_SIZE))
@@ -132,8 +131,7 @@ CBC_Decryption::CBC_Decryption(BlockCipher* ciph,
                                BlockCipherModePaddingMethod* pad,
                                const SymmetricKey& key,
                                const InitializationVector& iv) :
-   Buffered_Filter(ciph->parallelism() * ciph->BLOCK_SIZE,
-                   ciph->BLOCK_SIZE),
+   Buffered_Filter(ciph->parallel_bytes(), ciph->BLOCK_SIZE),
    cipher(ciph), padder(pad)
    {
    if(!padder->valid_blocksize(cipher->BLOCK_SIZE))
@@ -151,7 +149,7 @@ CBC_Decryption::CBC_Decryption(BlockCipher* ciph,
 */
 void CBC_Decryption::set_iv(const InitializationVector& iv)
    {
-   if(iv.length() != state.size())
+   if(!valid_iv_length(iv.length()))
       throw Invalid_IV_Length(name(), iv.length());
 
    state = iv.bits_of();
diff --git a/src/filters/modes/cbc/cbc.h b/src/filters/modes/cbc/cbc.h
index 6d9092041..4f682530b 100644
--- a/src/filters/modes/cbc/cbc.h
+++ b/src/filters/modes/cbc/cbc.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * CBC Encryption
 */
 class BOTAN_DLL CBC_Encryption : public Keyed_Filter,
@@ -24,13 +24,16 @@ class BOTAN_DLL CBC_Encryption : public Keyed_Filter,
    public:
       std::string name() const;
 
-      void set_iv(const InitializationVector&);
+      void set_iv(const InitializationVector& iv);
 
       void set_key(const SymmetricKey& key) { cipher->set_key(key); }
 
       bool valid_keylength(u32bit key_len) const
          { return cipher->valid_keylength(key_len); }
 
+      bool valid_iv_length(u32bit iv_len) const
+         { return (iv_len == cipher->BLOCK_SIZE); }
+
       CBC_Encryption(BlockCipher* cipher,
                      BlockCipherModePaddingMethod* padding);
 
@@ -52,7 +55,7 @@ class BOTAN_DLL CBC_Encryption : public Keyed_Filter,
       SecureVector<byte> state;
    };
 
-/*
+/**
 * CBC Decryption
 */
 class BOTAN_DLL CBC_Decryption : public Keyed_Filter,
@@ -61,13 +64,16 @@ class BOTAN_DLL CBC_Decryption : public Keyed_Filter,
    public:
       std::string name() const;
 
-      void set_iv(const InitializationVector&);
+      void set_iv(const InitializationVector& iv);
 
       void set_key(const SymmetricKey& key) { cipher->set_key(key); }
 
       bool valid_keylength(u32bit key_len) const
          { return cipher->valid_keylength(key_len); }
 
+      bool valid_iv_length(u32bit iv_len) const
+         { return (iv_len == cipher->BLOCK_SIZE); }
+
       CBC_Decryption(BlockCipher* cipher,
                      BlockCipherModePaddingMethod* padding);
 
diff --git a/src/filters/modes/cfb/cfb.cpp b/src/filters/modes/cfb/cfb.cpp
index ff1714b81..5b4575d56 100644
--- a/src/filters/modes/cfb/cfb.cpp
+++ b/src/filters/modes/cfb/cfb.cpp
@@ -54,7 +54,7 @@ CFB_Encryption::CFB_Encryption(BlockCipher* ciph,
 
 void CFB_Encryption::set_iv(const InitializationVector& iv)
    {
-   if(iv.length() != state.size())
+   if(!valid_iv_length(iv.length()))
       throw Invalid_IV_Length(name(), iv.length());
 
    state = iv.bits_of();
@@ -131,7 +131,7 @@ CFB_Decryption::CFB_Decryption(BlockCipher* ciph,
 
 void CFB_Decryption::set_iv(const InitializationVector& iv)
    {
-   if(iv.length() != state.size())
+   if(!valid_iv_length(iv.length()))
       throw Invalid_IV_Length(name(), iv.length());
 
    state = iv.bits_of();
diff --git a/src/filters/modes/cfb/cfb.h b/src/filters/modes/cfb/cfb.h
index 249ae21db..05fb9574f 100644
--- a/src/filters/modes/cfb/cfb.h
+++ b/src/filters/modes/cfb/cfb.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * CFB Encryption
 */
 class BOTAN_DLL CFB_Encryption : public Keyed_Filter
@@ -28,6 +28,9 @@ class BOTAN_DLL CFB_Encryption : public Keyed_Filter
       bool valid_keylength(u32bit key_len) const
          { return cipher->valid_keylength(key_len); }
 
+      bool valid_iv_length(u32bit iv_len) const
+         { return (iv_len == cipher->BLOCK_SIZE); }
+
       CFB_Encryption(BlockCipher* cipher, u32bit feedback = 0);
 
       CFB_Encryption(BlockCipher* cipher,
@@ -44,7 +47,7 @@ class BOTAN_DLL CFB_Encryption : public Keyed_Filter
       u32bit position, feedback;
    };
 
-/*
+/**
 * CFB Decryption
 */
 class BOTAN_DLL CFB_Decryption : public Keyed_Filter
@@ -59,6 +62,9 @@ class BOTAN_DLL CFB_Decryption : public Keyed_Filter
       bool valid_keylength(u32bit key_len) const
          { return cipher->valid_keylength(key_len); }
 
+      bool valid_iv_length(u32bit iv_len) const
+         { return (iv_len == cipher->BLOCK_SIZE); }
+
       CFB_Decryption(BlockCipher* cipher, u32bit feedback = 0);
 
       CFB_Decryption(BlockCipher* cipher,
diff --git a/src/filters/modes/cts/cts.cpp b/src/filters/modes/cts/cts.cpp
index b27b9b3c5..61df8897b 100644
--- a/src/filters/modes/cts/cts.cpp
+++ b/src/filters/modes/cts/cts.cpp
@@ -43,7 +43,7 @@ CTS_Encryption::CTS_Encryption(BlockCipher* ciph,
 */
 void CTS_Encryption::set_iv(const InitializationVector& iv)
    {
-   if(iv.length() != state.size())
+   if(!valid_iv_length(iv.length()))
       throw Invalid_IV_Length(name(), iv.length());
 
    state = iv.bits_of();
@@ -145,7 +145,7 @@ CTS_Decryption::CTS_Decryption(BlockCipher* ciph,
 */
 void CTS_Decryption::set_iv(const InitializationVector& iv)
    {
-   if(iv.length() != state.size())
+   if(!valid_iv_length(iv.length()))
       throw Invalid_IV_Length(name(), iv.length());
 
    state = iv.bits_of();
diff --git a/src/filters/modes/cts/cts.h b/src/filters/modes/cts/cts.h
index c15fa9510..e9c8ec592 100644
--- a/src/filters/modes/cts/cts.h
+++ b/src/filters/modes/cts/cts.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* CTS Encryption
+/**
+* CBC encryption with ciphertext stealing
 */
 class BOTAN_DLL CTS_Encryption : public Keyed_Filter
    {
@@ -28,6 +28,9 @@ class BOTAN_DLL CTS_Encryption : public Keyed_Filter
       bool valid_keylength(u32bit key_len) const
          { return cipher->valid_keylength(key_len); }
 
+      bool valid_iv_length(u32bit iv_len) const
+         { return (iv_len == cipher->BLOCK_SIZE); }
+
       CTS_Encryption(BlockCipher* cipher);
 
       CTS_Encryption(BlockCipher* cipher,
@@ -45,8 +48,8 @@ class BOTAN_DLL CTS_Encryption : public Keyed_Filter
       u32bit position;
    };
 
-/*
-* CTS Decryption
+/**
+* CBC decryption with ciphertext stealing
 */
 class BOTAN_DLL CTS_Decryption : public Keyed_Filter
    {
@@ -60,6 +63,9 @@ class BOTAN_DLL CTS_Decryption : public Keyed_Filter
       bool valid_keylength(u32bit key_len) const
          { return cipher->valid_keylength(key_len); }
 
+      bool valid_iv_length(u32bit iv_len) const
+         { return (iv_len == cipher->BLOCK_SIZE); }
+
       CTS_Decryption(BlockCipher* cipher);
 
       CTS_Decryption(BlockCipher* cipher,
diff --git a/src/filters/modes/eax/eax.h b/src/filters/modes/eax/eax.h
index e45e29ba8..8f79039d9 100644
--- a/src/filters/modes/eax/eax.h
+++ b/src/filters/modes/eax/eax.h
@@ -15,22 +15,42 @@
 
 namespace Botan {
 
-/*
+/**
 * EAX Base Class
 */
 class BOTAN_DLL EAX_Base : public Keyed_Filter
    {
    public:
-      void set_key(const SymmetricKey&);
-      void set_iv(const InitializationVector&);
-      void set_header(const byte[], u32bit);
+      void set_key(const SymmetricKey& key);
+      void set_iv(const InitializationVector& iv);
+
+      /**
+      * Set some additional data that is not included in the
+      * ciphertext but that will be authenticated.
+      * @param header the header contents
+      * @param header_len length of header in bytes
+      */
+      void set_header(const byte header[], u32bit header_len);
+
+      /**
+      * @return name of this mode
+      */
       std::string name() const;
 
-      bool valid_keylength(u32bit) const;
+      bool valid_keylength(u32bit key_len) const;
+
+      /**
+      * EAX supports arbitrary IV lengths
+      */
+      bool valid_iv_length(u32bit) const { return true; }
 
       ~EAX_Base() { delete ctr; delete cmac; }
    protected:
-      EAX_Base(BlockCipher*, u32bit);
+      /**
+      * @param cipher the cipher to use
+      * @param tag_size is how big the auth tag will be
+      */
+      EAX_Base(BlockCipher* cipher, u32bit tag_size);
       void start_msg();
 
       const u32bit BLOCK_SIZE, TAG_SIZE;
@@ -43,15 +63,25 @@ class BOTAN_DLL EAX_Base : public Keyed_Filter
       SecureVector<byte> ctr_buf;
    };
 
-/*
+/**
 * EAX Encryption
 */
 class BOTAN_DLL EAX_Encryption : public EAX_Base
    {
    public:
+      /**
+      * @param ciph the cipher to use
+      * @param tag_size is how big the auth tag will be
+      */
       EAX_Encryption(BlockCipher* ciph, u32bit tag_size = 0) :
          EAX_Base(ciph, tag_size) {}
 
+      /**
+      * @param ciph the cipher to use
+      * @param key the key to use
+      * @param iv the initially set IV
+      * @param tag_size is how big the auth tag will be
+      */
       EAX_Encryption(BlockCipher* ciph, const SymmetricKey& key,
                      const InitializationVector& iv,
                      u32bit tag_size) : EAX_Base(ciph, tag_size)
@@ -64,14 +94,24 @@ class BOTAN_DLL EAX_Encryption : public EAX_Base
       void end_msg();
    };
 
-/*
+/**
 * EAX Decryption
 */
 class BOTAN_DLL EAX_Decryption : public EAX_Base
    {
    public:
+      /**
+      * @param ciph the cipher to use
+      * @param tag_size is how big the auth tag will be
+      */
       EAX_Decryption(BlockCipher* ciph, u32bit tag_size = 0);
 
+      /**
+      * @param ciph the cipher to use
+      * @param key the key to use
+      * @param iv the initially set IV
+      * @param tag_size is how big the auth tag will be
+      */
       EAX_Decryption(BlockCipher* ciph, const SymmetricKey& key,
                      const InitializationVector& iv,
                      u32bit tag_size = 0);
diff --git a/src/filters/modes/ecb/ecb.cpp b/src/filters/modes/ecb/ecb.cpp
index 948daf6c2..965212abf 100644
--- a/src/filters/modes/ecb/ecb.cpp
+++ b/src/filters/modes/ecb/ecb.cpp
@@ -14,7 +14,7 @@ namespace Botan {
 */
 ECB_Encryption::ECB_Encryption(BlockCipher* ciph,
                                BlockCipherModePaddingMethod* pad) :
-   Buffered_Filter(ciph->BLOCK_SIZE * ciph->parallelism(), 0)
+   Buffered_Filter(ciph->parallel_bytes(), 0)
    {
    cipher = ciph;
    padder = pad;
@@ -28,7 +28,7 @@ ECB_Encryption::ECB_Encryption(BlockCipher* ciph,
 ECB_Encryption::ECB_Encryption(BlockCipher* ciph,
                                BlockCipherModePaddingMethod* pad,
                                const SymmetricKey& key) :
-   Buffered_Filter(ciph->BLOCK_SIZE * ciph->parallelism(), 0)
+   Buffered_Filter(ciph->parallel_bytes(), 0)
    {
    cipher = ciph;
    padder = pad;
@@ -111,7 +111,7 @@ void ECB_Encryption::buffered_final(const byte input[], u32bit input_length)
 */
 ECB_Decryption::ECB_Decryption(BlockCipher* ciph,
                                BlockCipherModePaddingMethod* pad) :
-   Buffered_Filter(ciph->BLOCK_SIZE * ciph->parallelism(), 1)
+   Buffered_Filter(ciph->parallel_bytes(), 1)
    {
    cipher = ciph;
    padder = pad;
@@ -125,7 +125,7 @@ ECB_Decryption::ECB_Decryption(BlockCipher* ciph,
 ECB_Decryption::ECB_Decryption(BlockCipher* ciph,
                                BlockCipherModePaddingMethod* pad,
                                const SymmetricKey& key) :
-   Buffered_Filter(ciph->BLOCK_SIZE * ciph->parallelism(), 1)
+   Buffered_Filter(ciph->parallel_bytes(), 1)
    {
    cipher = ciph;
    padder = pad;
diff --git a/src/filters/modes/ecb/ecb.h b/src/filters/modes/ecb/ecb.h
index 2b88191c7..eaf7fb143 100644
--- a/src/filters/modes/ecb/ecb.h
+++ b/src/filters/modes/ecb/ecb.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * ECB Encryption
 */
 class BOTAN_DLL ECB_Encryption : public Keyed_Filter,
@@ -49,7 +49,7 @@ class BOTAN_DLL ECB_Encryption : public Keyed_Filter,
       SecureVector<byte> temp;
    };
 
-/*
+/**
 * ECB Decryption
 */
 class BOTAN_DLL ECB_Decryption : public Keyed_Filter,
diff --git a/src/filters/modes/mode_pad/mode_pad.h b/src/filters/modes/mode_pad/mode_pad.h
index a486d3c1f..d6d1c5298 100644
--- a/src/filters/modes/mode_pad/mode_pad.h
+++ b/src/filters/modes/mode_pad/mode_pad.h
@@ -1,4 +1,4 @@
-/**
+/*
 * CBC Padding Methods
 * (C) 1999-2008 Jack Lloyd
 *
diff --git a/src/filters/modes/xts/xts.cpp b/src/filters/modes/xts/xts.cpp
index 26095e830..608c315ff 100644
--- a/src/filters/modes/xts/xts.cpp
+++ b/src/filters/modes/xts/xts.cpp
@@ -35,7 +35,8 @@ void poly_double(byte tweak[], u32bit size)
 */
 u32bit xts_parallelism(BlockCipher* cipher)
    {
-   return std::max<u32bit>(cipher->parallelism(), 2);
+   return std::max<u32bit>(cipher->parallel_bytes(),
+                           2 * cipher->BLOCK_SIZE);
    }
 
 }
@@ -44,8 +45,7 @@ u32bit xts_parallelism(BlockCipher* cipher)
 * XTS_Encryption constructor
 */
 XTS_Encryption::XTS_Encryption(BlockCipher* ciph) :
-   Buffered_Filter(xts_parallelism(ciph) * ciph->BLOCK_SIZE,
-                   ciph->BLOCK_SIZE + 1),
+   Buffered_Filter(xts_parallelism(ciph), ciph->BLOCK_SIZE + 1),
    cipher(ciph)
    {
    if(cipher->BLOCK_SIZE != 8 && cipher->BLOCK_SIZE != 16)
@@ -61,8 +61,7 @@ XTS_Encryption::XTS_Encryption(BlockCipher* ciph) :
 XTS_Encryption::XTS_Encryption(BlockCipher* ciph,
                                const SymmetricKey& key,
                                const InitializationVector& iv) :
-   Buffered_Filter(xts_parallelism(ciph) * ciph->BLOCK_SIZE,
-                   ciph->BLOCK_SIZE + 1),
+   Buffered_Filter(xts_parallelism(ciph), ciph->BLOCK_SIZE + 1),
    cipher(ciph)
    {
    if(cipher->BLOCK_SIZE != 8 && cipher->BLOCK_SIZE != 16)
@@ -88,7 +87,7 @@ std::string XTS_Encryption::name() const
 */
 void XTS_Encryption::set_iv(const InitializationVector& iv)
    {
-   if(iv.length() != cipher->BLOCK_SIZE)
+   if(!valid_iv_length(iv.length()))
       throw Invalid_IV_Length(name(), iv.length());
 
    const u32bit blocks_in_tweak = tweak.size() / cipher->BLOCK_SIZE;
@@ -218,8 +217,7 @@ void XTS_Encryption::buffered_final(const byte input[], u32bit length)
 * XTS_Decryption constructor
 */
 XTS_Decryption::XTS_Decryption(BlockCipher* ciph) :
-   Buffered_Filter(xts_parallelism(ciph) * ciph->BLOCK_SIZE,
-                   ciph->BLOCK_SIZE + 1),
+   Buffered_Filter(xts_parallelism(ciph), ciph->BLOCK_SIZE + 1),
    cipher(ciph)
    {
    if(cipher->BLOCK_SIZE != 8 && cipher->BLOCK_SIZE != 16)
@@ -235,8 +233,7 @@ XTS_Decryption::XTS_Decryption(BlockCipher* ciph) :
 XTS_Decryption::XTS_Decryption(BlockCipher* ciph,
                                const SymmetricKey& key,
                                const InitializationVector& iv) :
-   Buffered_Filter(xts_parallelism(ciph) * ciph->BLOCK_SIZE,
-                   ciph->BLOCK_SIZE + 1),
+   Buffered_Filter(xts_parallelism(ciph), ciph->BLOCK_SIZE + 1),
    cipher(ciph)
    {
    if(cipher->BLOCK_SIZE != 8 && cipher->BLOCK_SIZE != 16)
@@ -262,7 +259,7 @@ std::string XTS_Decryption::name() const
 */
 void XTS_Decryption::set_iv(const InitializationVector& iv)
    {
-   if(iv.length() != cipher->BLOCK_SIZE)
+   if(!valid_iv_length(iv.length()))
       throw Invalid_IV_Length(name(), iv.length());
 
    const u32bit blocks_in_tweak = tweak.size() / cipher->BLOCK_SIZE;
diff --git a/src/filters/modes/xts/xts.h b/src/filters/modes/xts/xts.h
index a01b1da1d..67c087c72 100644
--- a/src/filters/modes/xts/xts.h
+++ b/src/filters/modes/xts/xts.h
@@ -14,8 +14,8 @@
 
 namespace Botan {
 
-/*
-* XTS Encryption
+/**
+* IEEE P1619 XTS Encryption
 */
 class BOTAN_DLL XTS_Encryption : public Keyed_Filter,
                                  private Buffered_Filter
@@ -27,6 +27,9 @@ class BOTAN_DLL XTS_Encryption : public Keyed_Filter,
       bool valid_keylength(u32bit key_len) const
          { return cipher->valid_keylength(key_len); }
 
+      bool valid_iv_length(u32bit iv_len) const
+         { return (iv_len == cipher->BLOCK_SIZE); }
+
       std::string name() const;
 
       XTS_Encryption(BlockCipher* ciph);
@@ -48,8 +51,8 @@ class BOTAN_DLL XTS_Encryption : public Keyed_Filter,
       SecureVector<byte> tweak;
    };
 
-/*
-* XTS Decryption
+/**
+* IEEE P1619 XTS Encryption
 */
 class BOTAN_DLL XTS_Decryption : public Keyed_Filter,
                                  private Buffered_Filter
@@ -61,6 +64,9 @@ class BOTAN_DLL XTS_Decryption : public Keyed_Filter,
       bool valid_keylength(u32bit key_len) const
          { return cipher->valid_keylength(key_len); }
 
+      bool valid_iv_length(u32bit iv_len) const
+         { return (iv_len == cipher->BLOCK_SIZE); }
+
       std::string name() const;
 
       XTS_Decryption(BlockCipher* ciph);
diff --git a/src/filters/out_buf.h b/src/filters/out_buf.h
index fecbf9191..120729de4 100644
--- a/src/filters/out_buf.h
+++ b/src/filters/out_buf.h
@@ -14,7 +14,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Container of output buffers for Pipe
 */
 class Output_Buffers
diff --git a/src/filters/pbe.h b/src/filters/pbe.h
index f06d593d0..9add98872 100644
--- a/src/filters/pbe.h
+++ b/src/filters/pbe.h
@@ -25,16 +25,17 @@ class BOTAN_DLL PBE : public Filter
       * Set this filter's key.
       * @param pw the password to be used for the encryption
       */
-      virtual void set_key(const std::string&) = 0;
+      virtual void set_key(const std::string& pw) = 0;
 
       /**
       * Create a new random salt value and set the default iterations value.
+      * @param rng a random number generator
       */
       virtual void new_params(RandomNumberGenerator& rng) = 0;
 
       /**
       * DER encode the params (the number of iterations and the salt value)
-      * @return the encoded params
+      * @return encoded params
       */
       virtual MemoryVector<byte> encode_params() const = 0;
 
@@ -42,11 +43,11 @@ class BOTAN_DLL PBE : public Filter
       * Decode params and use them inside this Filter.
       * @param src a data source to read the encoded params from
       */
-      virtual void decode_params(DataSource&) = 0;
+      virtual void decode_params(DataSource& src) = 0;
 
       /**
       * Get this PBE's OID.
-      * @return the OID
+      * @return object identifier
       */
       virtual OID get_oid() const = 0;
    };
diff --git a/src/filters/pipe.h b/src/filters/pipe.h
index a927e1a0f..92f6c62db 100644
--- a/src/filters/pipe.h
+++ b/src/filters/pipe.h
@@ -23,21 +23,38 @@ namespace Botan {
 * collected for retrieval.  If you're familiar with the Unix shell
 * environment, this design will sound quite familiar.
 */
-
 class BOTAN_DLL Pipe : public DataSource
    {
    public:
+      /*
+      * An opaque type that identifies a message in this Pipe
+      */
       typedef u32bit message_id;
 
+      /**
+      * Exception if you use an invalid message as an argument to
+      * read, remaining, etc
+      */
       struct BOTAN_DLL Invalid_Message_Number : public Invalid_Argument
          {
+         /**
+         * @param where the error occured
+         * @param msg the invalid message id that was used
+         */
          Invalid_Message_Number(const std::string& where, message_id msg) :
             Invalid_Argument("Pipe::" + where + ": Invalid message number " +
                              std::to_string(msg))
             {}
          };
 
+      /**
+      * A meta-id for whatever the last message is
+      */
       static const message_id LAST_MESSAGE;
+
+      /**
+      * A meta-id for the default message (set with set_default_msg)
+      */
       static const message_id DEFAULT_MESSAGE;
 
       /**
@@ -100,7 +117,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;
 
@@ -108,9 +125,10 @@ class BOTAN_DLL Pipe : public DataSource
       * Read the default message from the pipe. Moves the internal
       * offset so that every call to read will return a new portion of
       * the message.
+      *
       * @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);
 
@@ -121,29 +139,32 @@ 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);
 
       /**
-      * Read a single byte from the pipe. Moves the internal offset so that
-      * every call to read will return a new portion of the message.
+      * Read a single byte from the pipe. Moves the internal offset so
+      * that every call to read will return a new portion of the
+      * message.
+      *
       * @param output the byte to write the result to
-      * @return the number of bytes actually read into output
+      * @param msg the message to read from
+      * @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);
 
@@ -153,7 +174,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;
 
@@ -164,7 +185,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;
@@ -175,11 +196,14 @@ 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;
 
+      /**
+      * @return currently set default message
+      */
       u32bit default_msg() const { return default_read; }
 
       /**
@@ -191,7 +215,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/filters/pk_filts/pk_filts.h b/src/filters/pk_filts/pk_filts.h
index 8bf3fc238..81d6c9008 100644
--- a/src/filters/pk_filts/pk_filts.h
+++ b/src/filters/pk_filts/pk_filts.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * PK_Encryptor Filter
 */
 class BOTAN_DLL PK_Encryptor_Filter : public Filter
@@ -31,7 +31,7 @@ class BOTAN_DLL PK_Encryptor_Filter : public Filter
       SecureVector<byte> buffer;
    };
 
-/*
+/**
 * PK_Decryptor Filter
 */
 class BOTAN_DLL PK_Decryptor_Filter : public Filter
@@ -46,7 +46,7 @@ class BOTAN_DLL PK_Decryptor_Filter : public Filter
       SecureVector<byte> buffer;
    };
 
-/*
+/**
 * PK_Signer Filter
 */
 class BOTAN_DLL PK_Signer_Filter : public Filter
@@ -65,7 +65,7 @@ class BOTAN_DLL PK_Signer_Filter : public Filter
       RandomNumberGenerator& rng;
    };
 
-/*
+/**
 * PK_Verifier Filter
 */
 class BOTAN_DLL PK_Verifier_Filter : public Filter
diff --git a/src/filters/secqueue.cpp b/src/filters/secqueue.cpp
index c8d1c5fbf..db0366bc8 100644
--- a/src/filters/secqueue.cpp
+++ b/src/filters/secqueue.cpp
@@ -10,12 +10,15 @@
 
 namespace Botan {
 
-/*
-* SecureQueueNode
+/**
+* A node in a SecureQueue
 */
 class SecureQueueNode
    {
    public:
+      SecureQueueNode()  { next = 0; start = end = 0; }
+      ~SecureQueueNode() { next = 0; start = end = 0; }
+
       u32bit write(const byte input[], u32bit length)
          {
          u32bit copied = std::min(length, buffer.size() - end);
@@ -23,6 +26,7 @@ class SecureQueueNode
          end += copied;
          return copied;
          }
+
       u32bit read(byte output[], u32bit length)
          {
          u32bit copied = std::min(length, end - start);
@@ -30,6 +34,7 @@ class SecureQueueNode
          start += copied;
          return copied;
          }
+
       u32bit peek(byte output[], u32bit length, u32bit offset = 0)
          {
          const u32bit left = end - start;
@@ -38,9 +43,8 @@ class SecureQueueNode
          copy_mem(output, buffer + start + offset, copied);
          return copied;
          }
+
       u32bit size() const { return (end - start); }
-      SecureQueueNode()  { next = 0; start = end = 0; }
-      ~SecureQueueNode() { next = 0; start = end = 0; }
    private:
       friend class SecureQueue;
       SecureQueueNode* next;
diff --git a/src/filters/secqueue.h b/src/filters/secqueue.h
index fc1fc213a..3cb486024 100644
--- a/src/filters/secqueue.h
+++ b/src/filters/secqueue.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* SecureQueue
+/**
+* A queue that knows how to zeroize itself
 */
 class BOTAN_DLL SecureQueue : public Fanout_Filter, public DataSource
    {
diff --git a/src/filters/zlib/zlib.cpp b/src/filters/zlib/zlib.cpp
index 171caa73f..148ed3e6c 100644
--- a/src/filters/zlib/zlib.cpp
+++ b/src/filters/zlib/zlib.cpp
@@ -53,8 +53,6 @@ void zlib_free(void* info_ptr, void* ptr)
    info->alloc->deallocate(ptr, i->second);
    }
 
-}
-
 /*
 * Wrapper Type for Zlib z_stream
 */
@@ -78,6 +76,8 @@ class Zlib_Stream
          }
    };
 
+}
+
 /*
 * Zlib_Compression Constructor
 */
diff --git a/src/filters/zlib/zlib.h b/src/filters/zlib/zlib.h
index 4a7f3bc80..2aa83aadf 100644
--- a/src/filters/zlib/zlib.h
+++ b/src/filters/zlib/zlib.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Zlib Compression Filter
 */
 class BOTAN_DLL Zlib_Compression : public Filter
@@ -23,9 +23,17 @@ class BOTAN_DLL Zlib_Compression : public Filter
       void start_msg();
       void end_msg();
 
+      /**
+      * Flush the compressor
+      */
       void flush();
 
-      Zlib_Compression(u32bit = 6);
+      /**
+      @param level how much effort to use on compressing (0 to 9);
+      higher levels are slower but tend to give better compression
+      */
+      Zlib_Compression(u32bit level = 6);
+
       ~Zlib_Compression() { clear(); }
    private:
       void clear();
@@ -34,7 +42,7 @@ class BOTAN_DLL Zlib_Compression : public Filter
       class Zlib_Stream* zlib;
    };
 
-/*
+/**
 * Zlib Decompression Filter
 */
 class BOTAN_DLL Zlib_Decompression : public Filter
diff --git a/src/hash/bmw/bmw_512.h b/src/hash/bmw/bmw_512.h
index c1c5238bd..d3c9c03c6 100644
--- a/src/hash/bmw/bmw_512.h
+++ b/src/hash/bmw/bmw_512.h
@@ -12,6 +12,9 @@
 
 namespace Botan {
 
+/**
+* Blue Midnight Wish 512 (Round 2 tweaked version)
+*/
 class BOTAN_DLL BMW_512 : public MDx_HashFunction
    {
    public:
diff --git a/src/hash/comb4p/comb4p.cpp b/src/hash/comb4p/comb4p.cpp
index 6ae36b9d3..ecbdc4671 100644
--- a/src/hash/comb4p/comb4p.cpp
+++ b/src/hash/comb4p/comb4p.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Comb4P hash combiner
 * (C) 2010 Jack Lloyd
 *
diff --git a/src/hash/comb4p/comb4p.h b/src/hash/comb4p/comb4p.h
index ce66bb9c9..550b70b14 100644
--- a/src/hash/comb4p/comb4p.h
+++ b/src/hash/comb4p/comb4p.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Comb4P hash combiner
 * (C) 2010 Jack Lloyd
 *
@@ -16,9 +16,13 @@ namespace Botan {
 * Combines two hash functions using a Feistel scheme. Described in
 * "On the Security of Hash Function Combiners", Anja Lehmann
 */
-class Comb4P : public HashFunction
+class BOTAN_DLL Comb4P : public HashFunction
    {
    public:
+      /**
+      * @param h1 the first hash
+      * @param h2 the second hash
+      */
       Comb4P(HashFunction* h1, HashFunction* h2);
 
       ~Comb4P() { delete hash1; delete hash2; }
diff --git a/src/hash/fork256/fork256.cpp b/src/hash/fork256/fork256.cpp
deleted file mode 100644
index bd85dfd7c..000000000
--- a/src/hash/fork256/fork256.cpp
+++ /dev/null
@@ -1,149 +0,0 @@
-/*
-* FORK-256
-* (C) 1999-2007 Jack Lloyd
-*
-* Distributed under the terms of the Botan license
-*/
-
-#include <botan/fork256.h>
-#include <botan/loadstor.h>
-#include <botan/rotate.h>
-
-namespace Botan {
-
-namespace {
-
-/*
-* FORK-256 Step Function
-*/
-inline void step(u32bit& A, u32bit& B, u32bit& C, u32bit& D,
-                 u32bit& E, u32bit& F, u32bit& G, u32bit& H,
-                 u32bit M1, u32bit M2, u32bit D1, u32bit D2)
-   {
-   u32bit T0, T1;
-
-   A += M1; T0 = A + (rotate_left(A,  7) ^ rotate_left(A, 22));
-   A += D1; T1 = A ^ (rotate_left(A, 13) + rotate_left(A, 27));
-
-   B = (B + T0) ^ T1;
-   C = (C + rotate_left(T0,  5)) ^ rotate_left(T1,  9);
-   D = (D + rotate_left(T0, 17)) ^ rotate_left(T1, 21);
-
-   E += M2; T0 = E ^ (rotate_left(E, 13) + rotate_left(E, 27));
-   E += D2; T1 = E + (rotate_left(E,  7) ^ rotate_left(E, 22));
-
-   F = (F + T0) ^ T1;
-   G = (G + rotate_left(T0,  9)) ^ rotate_left(T1,  5);
-   H = (H + rotate_left(T0, 21)) ^ rotate_left(T1, 17);
-   }
-
-}
-
-/*
-* FORK-256 Compression Function
-*/
-void FORK_256::compress_n(const byte input[], u32bit blocks)
-   {
-   const u32bit DELTA[16] = {
-      0x428A2F98, 0x71374491, 0xB5C0FBCF, 0xE9B5DBA5, 0x3956C25B, 0x59F111F1,
-      0x923F82A4, 0xAB1C5ED5, 0xD807AA98, 0x12835B01, 0x243185BE, 0x550C7DC3,
-      0x72BE5D74, 0x80DEB1FE, 0x9BDC06A7, 0xC19BF174
-   };
-
-   for(u32bit i = 0; i != blocks; ++i)
-      {
-      u32bit A1, B1, C1, D1, E1, F1, G1, H1;
-      u32bit A2, B2, C2, D2, E2, F2, G2, H2;
-      u32bit A3, B3, C3, D3, E3, F3, G3, H3;
-      u32bit A4, B4, C4, D4, E4, F4, G4, H4;
-
-      A1 = A2 = A3 = A4 = digest[0];
-      B1 = B2 = B3 = B4 = digest[1];
-      C1 = C2 = C3 = C4 = digest[2];
-      D1 = D2 = D3 = D4 = digest[3];
-      E1 = E2 = E3 = E4 = digest[4];
-      F1 = F2 = F3 = F4 = digest[5];
-      G1 = G2 = G3 = G4 = digest[6];
-      H1 = H2 = H3 = H4 = digest[7];
-
-      load_be(M.begin(), input, M.size());
-
-      step(A1, B1, C1, D1, E1, F1, G1, H1, M[ 0], M[ 1], DELTA[ 0], DELTA[ 1]);
-      step(A2, B2, C2, D2, E2, F2, G2, H2, M[14], M[15], DELTA[15], DELTA[14]);
-      step(A3, B3, C3, D3, E3, F3, G3, H3, M[ 7], M[ 6], DELTA[ 1], DELTA[ 0]);
-      step(A4, B4, C4, D4, E4, F4, G4, H4, M[ 5], M[12], DELTA[14], DELTA[15]);
-
-      step(H1, A1, B1, C1, D1, E1, F1, G1, M[ 2], M[ 3], DELTA[ 2], DELTA[ 3]);
-      step(H2, A2, B2, C2, D2, E2, F2, G2, M[11], M[ 9], DELTA[13], DELTA[12]);
-      step(H3, A3, B3, C3, D3, E3, F3, G3, M[10], M[14], DELTA[ 3], DELTA[ 2]);
-      step(H4, A4, B4, C4, D4, E4, F4, G4, M[ 1], M[ 8], DELTA[12], DELTA[13]);
-
-      step(G1, H1, A1, B1, C1, D1, E1, F1, M[ 4], M[ 5], DELTA[ 4], DELTA[ 5]);
-      step(G2, H2, A2, B2, C2, D2, E2, F2, M[ 8], M[10], DELTA[11], DELTA[10]);
-      step(G3, H3, A3, B3, C3, D3, E3, F3, M[13], M[ 2], DELTA[ 5], DELTA[ 4]);
-      step(G4, H4, A4, B4, C4, D4, E4, F4, M[15], M[ 0], DELTA[10], DELTA[11]);
-
-      step(F1, G1, H1, A1, B1, C1, D1, E1, M[ 6], M[ 7], DELTA[ 6], DELTA[ 7]);
-      step(F2, G2, H2, A2, B2, C2, D2, E2, M[ 3], M[ 4], DELTA[ 9], DELTA[ 8]);
-      step(F3, G3, H3, A3, B3, C3, D3, E3, M[ 9], M[12], DELTA[ 7], DELTA[ 6]);
-      step(F4, G4, H4, A4, B4, C4, D4, E4, M[13], M[11], DELTA[ 8], DELTA[ 9]);
-
-      step(E1, F1, G1, H1, A1, B1, C1, D1, M[ 8], M[ 9], DELTA[ 8], DELTA[ 9]);
-      step(E2, F2, G2, H2, A2, B2, C2, D2, M[ 2], M[13], DELTA[ 7], DELTA[ 6]);
-      step(E3, F3, G3, H3, A3, B3, C3, D3, M[11], M[ 4], DELTA[ 9], DELTA[ 8]);
-      step(E4, F4, G4, H4, A4, B4, C4, D4, M[ 3], M[10], DELTA[ 6], DELTA[ 7]);
-
-      step(D1, E1, F1, G1, H1, A1, B1, C1, M[10], M[11], DELTA[10], DELTA[11]);
-      step(D2, E2, F2, G2, H2, A2, B2, C2, M[ 0], M[ 5], DELTA[ 5], DELTA[ 4]);
-      step(D3, E3, F3, G3, H3, A3, B3, C3, M[15], M[ 8], DELTA[11], DELTA[10]);
-      step(D4, E4, F4, G4, H4, A4, B4, C4, M[ 9], M[ 2], DELTA[ 4], DELTA[ 5]);
-
-      step(C1, D1, E1, F1, G1, H1, A1, B1, M[12], M[13], DELTA[12], DELTA[13]);
-      step(C2, D2, E2, F2, G2, H2, A2, B2, M[ 6], M[ 7], DELTA[ 3], DELTA[ 2]);
-      step(C3, D3, E3, F3, G3, H3, A3, B3, M[ 5], M[ 0], DELTA[13], DELTA[12]);
-      step(C4, D4, E4, F4, G4, H4, A4, B4, M[ 7], M[14], DELTA[ 2], DELTA[ 3]);
-
-      step(B1, C1, D1, E1, F1, G1, H1, A1, M[14], M[15], DELTA[14], DELTA[15]);
-      step(B2, C2, D2, E2, F2, G2, H2, A2, M[12], M[ 1], DELTA[ 1], DELTA[ 0]);
-      step(B3, C3, D3, E3, F3, G3, H3, A3, M[ 1], M[ 3], DELTA[15], DELTA[14]);
-      step(B4, C4, D4, E4, F4, G4, H4, A4, M[ 4], M[ 6], DELTA[ 0], DELTA[ 1]);
-
-      digest[0] += (A1 + A2) ^ (A3 + A4);
-      digest[1] += (B1 + B2) ^ (B3 + B4);
-      digest[2] += (C1 + C2) ^ (C3 + C4);
-      digest[3] += (D1 + D2) ^ (D3 + D4);
-      digest[4] += (E1 + E2) ^ (E3 + E4);
-      digest[5] += (F1 + F2) ^ (F3 + F4);
-      digest[6] += (G1 + G2) ^ (G3 + G4);
-      digest[7] += (H1 + H2) ^ (H3 + H4);
-
-      input += HASH_BLOCK_SIZE;
-      }
-   }
-
-/*
-* Copy out the digest
-*/
-void FORK_256::copy_out(byte output[])
-   {
-   for(u32bit j = 0; j != OUTPUT_LENGTH; j += 4)
-      store_be(digest[j/4], output + j);
-   }
-
-/*
-* Clear memory of sensitive data
-*/
-void FORK_256::clear()
-   {
-   MDx_HashFunction::clear();
-   digest[0] = 0x6A09E667;
-   digest[1] = 0xBB67AE85;
-   digest[2] = 0x3C6EF372;
-   digest[3] = 0xA54FF53A;
-   digest[4] = 0x510E527F;
-   digest[5] = 0x9B05688C;
-   digest[6] = 0x1F83D9AB;
-   digest[7] = 0x5BE0CD19;
-   }
-
-}
diff --git a/src/hash/fork256/fork256.h b/src/hash/fork256/fork256.h
deleted file mode 100644
index ed945b9d8..000000000
--- a/src/hash/fork256/fork256.h
+++ /dev/null
@@ -1,35 +0,0 @@
-/*
-* FORK-256
-* (C) 1999-2007 Jack Lloyd
-*
-* Distributed under the terms of the Botan license
-*/
-
-#ifndef BOTAN_FORK_256_H__
-#define BOTAN_FORK_256_H__
-
-#include <botan/mdx_hash.h>
-
-namespace Botan {
-
-/*
-* FORK-256
-*/
-class BOTAN_DLL FORK_256 : public MDx_HashFunction
-   {
-   public:
-      void clear();
-      std::string name() const { return "FORK-256"; }
-      HashFunction* clone() const { return new FORK_256; }
-      FORK_256() : MDx_HashFunction(32, 64, true, true) { clear(); }
-   private:
-      void compress_n(const byte[], u32bit blocks);
-      void copy_out(byte[]);
-
-      SecureVector<u32bit, 8> digest;
-      SecureVector<u32bit, 16> M;
-   };
-
-}
-
-#endif
diff --git a/src/hash/fork256/info.txt b/src/hash/fork256/info.txt
deleted file mode 100644
index c2f8c47f2..000000000
--- a/src/hash/fork256/info.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-define FORK_256
-
-<requires>
-mdx_hash
-</requires>
diff --git a/src/hash/gost_3411/gost_3411.h b/src/hash/gost_3411/gost_3411.h
index d2bada7ab..04417d6fd 100644
--- a/src/hash/gost_3411/gost_3411.h
+++ b/src/hash/gost_3411/gost_3411.h
@@ -1,4 +1,4 @@
-/**
+/*
 * GOST 34.11
 * (C) 2009 Jack Lloyd
 *
@@ -24,7 +24,7 @@ class BOTAN_DLL GOST_34_11 : public HashFunction
       HashFunction* clone() const { return new GOST_34_11; }
 
       GOST_34_11();
-   protected:
+   private:
       void compress_n(const byte input[], u32bit blocks);
 
       void add_data(const byte[], u32bit);
diff --git a/src/hash/has160/has160.h b/src/hash/has160/has160.h
index 210145484..a82e4c579 100644
--- a/src/hash/has160/has160.h
+++ b/src/hash/has160/has160.h
@@ -12,8 +12,9 @@
 
 namespace Botan {
 
-/*
-* HAS-160
+/**
+* HAS-160, a Korean hash function standardized in
+* TTAS.KO-12.0011/R1. Used in conjuction with KCDSA
 */
 class BOTAN_DLL HAS_160 : public MDx_HashFunction
    {
diff --git a/src/hash/hash.h b/src/hash/hash.h
index 1098951d8..cdf90f184 100644
--- a/src/hash/hash.h
+++ b/src/hash/hash.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Hash Function Base Class
 * (C) 1999-2008 Jack Lloyd
 *
@@ -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;
 
@@ -40,8 +40,13 @@ class BOTAN_DLL HashFunction : public BufferedComputation
       */
       virtual void clear() = 0;
 
+      /**
+      * @param hash_len the output length
+      * @param block_len the internal block size (if applicable)
+      */
       HashFunction(u32bit hash_len, u32bit block_len = 0) :
          BufferedComputation(hash_len), HASH_BLOCK_SIZE(block_len) {}
+
       virtual ~HashFunction() {}
    private:
       HashFunction& operator=(const HashFunction&);
diff --git a/src/hash/md2/md2.h b/src/hash/md2/md2.h
index df056dc12..9d39d8913 100644
--- a/src/hash/md2/md2.h
+++ b/src/hash/md2/md2.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * MD2
 */
 class BOTAN_DLL MD2 : public HashFunction
diff --git a/src/hash/md4/md4.h b/src/hash/md4/md4.h
index 843727f6d..44d60406a 100644
--- a/src/hash/md4/md4.h
+++ b/src/hash/md4/md4.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * MD4
 */
 class BOTAN_DLL MD4 : public MDx_HashFunction
@@ -24,7 +24,6 @@ class BOTAN_DLL MD4 : public MDx_HashFunction
       MD4() : MDx_HashFunction(16, 64, false, true) { clear(); }
    protected:
       void compress_n(const byte input[], u32bit blocks);
-      void hash_old(const byte[]);
       void copy_out(byte[]);
 
       SecureVector<u32bit, 16> M;
diff --git a/src/hash/md4_ia32/md4_ia32.h b/src/hash/md4_ia32/md4_ia32.h
index f01d148f4..ef8060d3f 100644
--- a/src/hash/md4_ia32/md4_ia32.h
+++ b/src/hash/md4_ia32/md4_ia32.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* MD4
+/**
+* MD4 using x86 assembly
 */
 class BOTAN_DLL MD4_IA32 : public MD4
    {
diff --git a/src/hash/md5/md5.h b/src/hash/md5/md5.h
index d1f294a87..d0706ab4b 100644
--- a/src/hash/md5/md5.h
+++ b/src/hash/md5/md5.h
@@ -1,4 +1,4 @@
-/**
+/*
 * MD5
 * (C) 1999-2008 Jack Lloyd
 *
diff --git a/src/hash/md5_ia32/md5_ia32.h b/src/hash/md5_ia32/md5_ia32.h
index 723d724de..b65490760 100644
--- a/src/hash/md5_ia32/md5_ia32.h
+++ b/src/hash/md5_ia32/md5_ia32.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* MD5
+/**
+* MD5 in x86 assembly
 */
 class BOTAN_DLL MD5_IA32 : public MD5
    {
diff --git a/src/hash/mdx_hash/mdx_hash.cpp b/src/hash/mdx_hash/mdx_hash.cpp
index 28402c2c5..bf571076e 100644
--- a/src/hash/mdx_hash/mdx_hash.cpp
+++ b/src/hash/mdx_hash/mdx_hash.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Merkle-Damgard Hash Function
 * (C) 1999-2008 Jack Lloyd
 *
@@ -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 2d70deed3..087c7fc46 100644
--- a/src/hash/mdx_hash/mdx_hash.h
+++ b/src/hash/mdx_hash/mdx_hash.h
@@ -1,4 +1,4 @@
-/**
+/*
 * MDx Hash Function
 * (C) 1999-2008 Jack Lloyd
 *
@@ -18,16 +18,44 @@ 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[], u32bit);
+      void add_data(const byte input[], u32bit length);
       void final_result(byte output[]);
-      virtual void compress_n(const byte block[], u32bit block_n) = 0;
+
+      /**
+      * Run the hash's compression function over a set of blocks
+      * @param blocks the input
+      * @param block_n the number of blocks
+      */
+      virtual void compress_n(const byte blocks[], u32bit block_n) = 0;
 
       void clear();
-      virtual void copy_out(byte[]) = 0;
-      virtual void write_count(byte[]);
+
+      /**
+      * Copy the output to the buffer
+      * @param buffer to put the output into
+      */
+      virtual void copy_out(byte buffer[]) = 0;
+
+      /**
+      * Write the count, if used, to this spot
+      * @param out where to write the counter to
+      */
+      virtual void write_count(byte out[]);
    private:
       SecureVector<byte> buffer;
       u64bit count;
diff --git a/src/hash/par_hash/par_hash.h b/src/hash/par_hash/par_hash.h
index 874e491b1..d82a74a19 100644
--- a/src/hash/par_hash/par_hash.h
+++ b/src/hash/par_hash/par_hash.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* Parallel
+/**
+* Parallel Hashes
 */
 class BOTAN_DLL Parallel : public HashFunction
    {
@@ -23,7 +23,10 @@ class BOTAN_DLL Parallel : public HashFunction
       std::string name() const;
       HashFunction* clone() const;
 
-      Parallel(const std::vector<HashFunction*>&);
+      /**
+      * @param hashes a set of hashes to compute in parallel
+      */
+      Parallel(const std::vector<HashFunction*>& hashes);
       ~Parallel();
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/hash/rmd128/rmd128.h b/src/hash/rmd128/rmd128.h
index 9ae43483c..c7c7f4580 100644
--- a/src/hash/rmd128/rmd128.h
+++ b/src/hash/rmd128/rmd128.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * RIPEMD-128
 */
 class BOTAN_DLL RIPEMD_128 : public MDx_HashFunction
@@ -22,7 +22,7 @@ class BOTAN_DLL RIPEMD_128 : public MDx_HashFunction
       std::string name() const { return "RIPEMD-128"; }
       HashFunction* clone() const { return new RIPEMD_128; }
       RIPEMD_128() : MDx_HashFunction(16, 64, false, true) { clear(); }
-  private:
+   private:
       void compress_n(const byte[], u32bit blocks);
       void copy_out(byte[]);
 
diff --git a/src/hash/rmd160/rmd160.h b/src/hash/rmd160/rmd160.h
index 399d5a7c3..0b6e847f0 100644
--- a/src/hash/rmd160/rmd160.h
+++ b/src/hash/rmd160/rmd160.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * RIPEMD-160
 */
 class BOTAN_DLL RIPEMD_160 : public MDx_HashFunction
diff --git a/src/hash/sha1/sha160.h b/src/hash/sha1/sha160.h
index cb7e63821..c66831a1e 100644
--- a/src/hash/sha1/sha160.h
+++ b/src/hash/sha1/sha160.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* SHA-160
+/**
+* NIST's SHA-160
 */
 class BOTAN_DLL SHA_160 : public MDx_HashFunction
    {
@@ -24,6 +24,12 @@ class BOTAN_DLL SHA_160 : public MDx_HashFunction
       SHA_160();
 
    protected:
+      /**
+      * Set a custom size for the W array. Normally 80, but some
+      * subclasses need slightly more for best performance/internal
+      * constraints
+      * @param W_size how big to make W
+      */
       SHA_160(u32bit W_size);
 
       void compress_n(const byte[], u32bit blocks);
diff --git a/src/hash/sha1_amd64/sha1_amd64.h b/src/hash/sha1_amd64/sha1_amd64.h
index f182627a8..6cf3b0fb7 100644
--- a/src/hash/sha1_amd64/sha1_amd64.h
+++ b/src/hash/sha1_amd64/sha1_amd64.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* SHA-160
+/**
+* SHA-160 in x86-64 assembly
 */
 class BOTAN_DLL SHA_160_AMD64 : public SHA_160
    {
diff --git a/src/hash/sha1_ia32/sha1_ia32.h b/src/hash/sha1_ia32/sha1_ia32.h
index fd34971cb..f579fbc90 100644
--- a/src/hash/sha1_ia32/sha1_ia32.h
+++ b/src/hash/sha1_ia32/sha1_ia32.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* SHA-160
+/**
+* SHA-160 in x86 assembly
 */
 class BOTAN_DLL SHA_160_IA32 : public SHA_160
    {
diff --git a/src/hash/sha1_sse2/sha1_sse2.h b/src/hash/sha1_sse2/sha1_sse2.h
index 1c4b4cca7..90935c737 100644
--- a/src/hash/sha1_sse2/sha1_sse2.h
+++ b/src/hash/sha1_sse2/sha1_sse2.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* SHA-160
+/**
+* SHA-160 using SSE2 for the message expansion
 */
 class BOTAN_DLL SHA_160_SSE2 : public SHA_160
    {
diff --git a/src/hash/sha2/sha2_32.h b/src/hash/sha2/sha2_32.h
index e157fd657..e8e60d07c 100644
--- a/src/hash/sha2/sha2_32.h
+++ b/src/hash/sha2/sha2_32.h
@@ -13,13 +13,17 @@
 
 namespace Botan {
 
-/*
-* SHA-{224,256} Base
+/**
+* Base class for the 32-bit SHA-2 hashes (SHA-224 and SHA-256)
 */
 class BOTAN_DLL SHA_224_256_BASE : public MDx_HashFunction
    {
    protected:
       void clear();
+
+      /**
+      * @param out output size in bytes
+      */
       SHA_224_256_BASE(u32bit out) :
          MDx_HashFunction(out, 64, true, true) { clear(); }
 
@@ -30,7 +34,7 @@ class BOTAN_DLL SHA_224_256_BASE : public MDx_HashFunction
       void copy_out(byte[]);
    };
 
-/*
+/**
 * SHA-224
 */
 class BOTAN_DLL SHA_224 : public SHA_224_256_BASE
@@ -42,7 +46,7 @@ class BOTAN_DLL SHA_224 : public SHA_224_256_BASE
       SHA_224() : SHA_224_256_BASE(28) { clear(); }
    };
 
-/*
+/**
 * SHA-256
 */
 class BOTAN_DLL SHA_256 : public SHA_224_256_BASE
diff --git a/src/hash/sha2/sha2_64.h b/src/hash/sha2/sha2_64.h
index ed261b1c2..bf87eb62d 100644
--- a/src/hash/sha2/sha2_64.h
+++ b/src/hash/sha2/sha2_64.h
@@ -12,14 +12,17 @@
 
 namespace Botan {
 
-/*
-* SHA-{384,512} Base
+/**
+* Base class for the 64-bit SHA-2 hashes (SHA-384 and SHA-512)
 */
 class BOTAN_DLL SHA_384_512_BASE : public MDx_HashFunction
    {
    protected:
       void clear();
 
+      /**
+      * @param out output size in bytes
+      */
       SHA_384_512_BASE(u32bit out) :
          MDx_HashFunction(out, 128, true, true, 16) {}
 
@@ -31,7 +34,7 @@ class BOTAN_DLL SHA_384_512_BASE : public MDx_HashFunction
       SecureVector<u64bit, 80> W;
    };
 
-/*
+/**
 * SHA-384
 */
 class BOTAN_DLL SHA_384 : public SHA_384_512_BASE
@@ -43,7 +46,7 @@ class BOTAN_DLL SHA_384 : public SHA_384_512_BASE
       SHA_384() : SHA_384_512_BASE(48) { clear(); }
    };
 
-/*
+/**
 * SHA-512
 */
 class BOTAN_DLL SHA_512 : public SHA_384_512_BASE
diff --git a/src/hash/skein/skein_512.cpp b/src/hash/skein/skein_512.cpp
index 42fc4ba37..3330f4925 100644
--- a/src/hash/skein/skein_512.cpp
+++ b/src/hash/skein/skein_512.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * The Skein-512 hash function
 * (C) 2009 Jack Lloyd
 *
diff --git a/src/hash/skein/skein_512.h b/src/hash/skein/skein_512.h
index 222db5d68..5d17fa564 100644
--- a/src/hash/skein/skein_512.h
+++ b/src/hash/skein/skein_512.h
@@ -1,4 +1,4 @@
-/**
+/*
 * The Skein-512 hash function
 * (C) 2009 Jack Lloyd
 *
@@ -14,9 +14,17 @@
 
 namespace Botan {
 
+/**
+* Skein-512, a SHA-3 candidate
+*/
 class BOTAN_DLL Skein_512 : public HashFunction
    {
    public:
+      /**
+      * @param output_bits the output size of Skein in bits
+      * @param personalization is a string that will paramaterize the
+      * hash output
+      */
       Skein_512(u32bit output_bits = 512,
                 const std::string& personalization = "");
 
diff --git a/src/hash/tiger/tiger.h b/src/hash/tiger/tiger.h
index 918e2de3c..380f6eb24 100644
--- a/src/hash/tiger/tiger.h
+++ b/src/hash/tiger/tiger.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Tiger
 */
 class BOTAN_DLL Tiger : public MDx_HashFunction
@@ -20,8 +20,17 @@ class BOTAN_DLL Tiger : public MDx_HashFunction
    public:
       void clear();
       std::string name() const;
-      HashFunction* clone() const { return new Tiger(OUTPUT_LENGTH); }
-      Tiger(u32bit = 24, u32bit = 3);
+
+      HashFunction* clone() const
+         {
+         return new Tiger(OUTPUT_LENGTH, PASS);
+         }
+
+      /**
+      * @param out_size specifies the output length; can be 16, 20, or 24
+      * @param passes to make in the algorithm
+      */
+      Tiger(u32bit out_size = 24, u32bit passes = 3);
    private:
       void compress_n(const byte[], u32bit block);
       void copy_out(byte[]);
diff --git a/src/hash/whirlpool/whrlpool.h b/src/hash/whirlpool/whrlpool.h
index 4711fafa3..e28053d4f 100644
--- a/src/hash/whirlpool/whrlpool.h
+++ b/src/hash/whirlpool/whrlpool.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Whirlpool
 */
 class BOTAN_DLL Whirlpool : public MDx_HashFunction
diff --git a/src/kdf/kdf.h b/src/kdf/kdf.h
index 67078218f..ecf7f4621 100644
--- a/src/kdf/kdf.h
+++ b/src/kdf/kdf.h
@@ -13,31 +13,69 @@
 
 namespace Botan {
 
-/*
+/**
 * Key Derivation Function
 */
 class BOTAN_DLL KDF
    {
    public:
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param salt a diversifier
+      */
       SecureVector<byte> derive_key(u32bit key_len,
                                     const MemoryRegion<byte>& secret,
                                     const std::string& salt = "") const;
 
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param salt a diversifier
+      */
       SecureVector<byte> derive_key(u32bit key_len,
                                     const MemoryRegion<byte>& secret,
                                     const MemoryRegion<byte>& salt) const;
 
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param salt a diversifier
+      * @param salt_len size of salt in bytes
+      */
       SecureVector<byte> derive_key(u32bit key_len,
                                     const MemoryRegion<byte>& secret,
-                                    const byte salt[], u32bit salt_len) const;
+                                    const byte salt[],
+                                    u32bit salt_len) const;
 
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param secret_len size of secret in bytes
+      * @param salt a diversifier
+      */
       SecureVector<byte> derive_key(u32bit key_len,
-                                    const byte secret[], u32bit secret_len,
+                                    const byte secret[],
+                                    u32bit secret_len,
                                     const std::string& salt = "") const;
 
+      /**
+      * Derive a key
+      * @param key_len the desired output length in bytes
+      * @param secret the secret input
+      * @param secret_len size of secret in bytes
+      * @param salt a diversifier
+      * @param salt_len size of salt in bytes
+      */
       SecureVector<byte> derive_key(u32bit key_len,
-                                    const byte secret[], u32bit secret_len,
-                                    const byte salt[], u32bit salt_len) const;
+                                    const byte secret[],
+                                    u32bit secret_len,
+                                    const byte salt[],
+                                    u32bit salt_len) const;
 
       virtual ~KDF() {}
    private:
@@ -47,7 +85,7 @@ class BOTAN_DLL KDF
                 const byte salt[], u32bit salt_len) const = 0;
    };
 
-/*
+/**
 * Mask Generation Function
 */
 class BOTAN_DLL MGF
diff --git a/src/kdf/kdf1/kdf1.h b/src/kdf/kdf1/kdf1.h
index d657cccc2..80ea470a9 100644
--- a/src/kdf/kdf1/kdf1.h
+++ b/src/kdf/kdf1/kdf1.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* KDF1
+/**
+* KDF1, from IEEE 1363
 */
 class BOTAN_DLL KDF1 : public KDF
    {
diff --git a/src/kdf/kdf2/kdf2.h b/src/kdf/kdf2/kdf2.h
index f748bed0f..1f01008c0 100644
--- a/src/kdf/kdf2/kdf2.h
+++ b/src/kdf/kdf2/kdf2.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* KDF2
+/**
+* KDF2, from IEEE 1363
 */
 class BOTAN_DLL KDF2 : public KDF
    {
diff --git a/src/kdf/mgf1/mgf1.h b/src/kdf/mgf1/mgf1.h
index 799ba7eed..2f7655fe2 100644
--- a/src/kdf/mgf1/mgf1.h
+++ b/src/kdf/mgf1/mgf1.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* MGF1 (Mask Generation Function)
+/**
+* MGF1 from PKCS #1 v2.0
 */
 class BOTAN_DLL MGF1 : public MGF
    {
diff --git a/src/kdf/ssl_prf/prf_ssl3.h b/src/kdf/ssl_prf/prf_ssl3.h
index 165fc7c3c..7d968eda1 100644
--- a/src/kdf/ssl_prf/prf_ssl3.h
+++ b/src/kdf/ssl_prf/prf_ssl3.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* SSL3 PRF
+/**
+* PRF used in SSLv3
 */
 class BOTAN_DLL SSL3_PRF : public KDF
    {
diff --git a/src/kdf/tls_prf/prf_tls.h b/src/kdf/tls_prf/prf_tls.h
index 6d1787609..c7ad81a97 100644
--- a/src/kdf/tls_prf/prf_tls.h
+++ b/src/kdf/tls_prf/prf_tls.h
@@ -14,8 +14,8 @@
 
 namespace Botan {
 
-/*
-* TLS PRF
+/**
+* PRF used in TLS 1.0/1.1
 */
 class BOTAN_DLL TLS_PRF : public KDF
    {
@@ -31,8 +31,8 @@ class BOTAN_DLL TLS_PRF : public KDF
       MessageAuthenticationCode* hmac_sha1;
    };
 
-/*
-* TLS 1.2 PRF
+/**
+* PRF used in TLS 1.2
 */
 class BOTAN_DLL TLS_12_PRF : public KDF
    {
diff --git a/src/kdf/x942_prf/prf_x942.h b/src/kdf/x942_prf/prf_x942.h
index f957566b0..a5fe9f351 100644
--- a/src/kdf/x942_prf/prf_x942.h
+++ b/src/kdf/x942_prf/prf_x942.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* X9.42 PRF
+/**
+* PRF from ANSI X9.42
 */
 class BOTAN_DLL X942_PRF : public KDF
    {
diff --git a/src/libstate/botan.h b/src/libstate/botan.h
index a88edb59b..42d3dc392 100644
--- a/src/libstate/botan.h
+++ b/src/libstate/botan.h
@@ -1,4 +1,4 @@
-/**
+/*
 * A vague catch all include file for Botan
 * (C) 1999-2007 Jack Lloyd
 *
diff --git a/src/libstate/init.cpp b/src/libstate/init.cpp
index 0d9a2420c..a65098d5a 100644
--- a/src/libstate/init.cpp
+++ b/src/libstate/init.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Default Initialization Function
 * (C) 1999-2009 Jack Lloyd
 *
diff --git a/src/libstate/init.h b/src/libstate/init.h
index 254f9458b..2d70e4370 100644
--- a/src/libstate/init.h
+++ b/src/libstate/init.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Library Initialization
 * (C) 1999-2008 Jack Lloyd
 *
@@ -22,13 +22,20 @@ namespace Botan {
 class BOTAN_DLL LibraryInitializer
    {
    public:
+      /**
+      * Initialize the library
+      * @param options a string listing initialization options
+      */
       static void initialize(const std::string& options = "");
 
+      /**
+      * Shutdown the library
+      */
       static void deinitialize();
 
       /**
       * Initialize the library
-      * @param thread_safe if the library should use a thread-safe mutex
+      * @param options a string listing initialization options
       */
       LibraryInitializer(const std::string& options = "")
          { LibraryInitializer::initialize(options); }
diff --git a/src/libstate/libstate.h b/src/libstate/libstate.h
index 5af55e9d8..f3abdf87a 100644
--- a/src/libstate/libstate.h
+++ b/src/libstate/libstate.h
@@ -34,12 +34,12 @@ class BOTAN_DLL Library_State
       void initialize();
 
       /**
-      * @return the global Algorithm_Factory
+      * @return global Algorithm_Factory
       */
       Algorithm_Factory& algorithm_factory() const;
 
       /**
-      * @return the global RandomNumberGenerator
+      * @return global RandomNumberGenerator
       */
       RandomNumberGenerator& global_rng();
 
@@ -71,8 +71,7 @@ class BOTAN_DLL Library_State
                       const std::string& key);
 
       /**
-      * Check whether a certain parameter is set
-      * or not.
+      * Check whether a certain parameter is set or not.
       * @param section the section of the desired key
       * @param key the desired keys name
       * @result true if the parameters value is set,
@@ -85,6 +84,7 @@ class BOTAN_DLL Library_State
       * Set a configuration parameter.
       * @param section the section of the desired key
       * @param key the desired keys name
+      * @param value the new value
       * @param overwrite if set to true, the parameters value
       * will be overwritten even if it is already set, otherwise
       * no existing values will be overwritten.
@@ -144,7 +144,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 833b28f67..c980e5f8d 100644
--- a/src/libstate/look_pk.h
+++ b/src/libstate/look_pk.h
@@ -15,9 +15,11 @@ namespace Botan {
 
 /**
 * Public key encryptor factory method.
+* @deprecated Instantiate object from pubkey.h directly
+*
 * @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)
@@ -27,9 +29,11 @@ inline PK_Encryptor* get_pk_encryptor(const Public_Key& key,
 
 /**
 * Public key decryptor factory method.
+* @deprecated Instantiate object from pubkey.h directly
+*
 * @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)
@@ -39,10 +43,12 @@ inline PK_Decryptor* get_pk_decryptor(const Private_Key& key,
 
 /**
 * Public key signer factory method.
+* @deprecated Instantiate object from pubkey.h directly
+*
 * @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,
@@ -53,10 +59,12 @@ inline PK_Signer* get_pk_signer(const Private_Key& key,
 
 /**
 * Public key verifier factory method.
+* @deprecated Instantiate object from pubkey.h directly
+*
 * @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,
@@ -67,9 +75,11 @@ inline PK_Verifier* get_pk_verifier(const Public_Key& key,
 
 /**
 * Public key key agreement factory method.
+* @deprecated Instantiate object from pubkey.h directly
+*
 * @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.cpp b/src/libstate/lookup.cpp
index 01f4a3d42..586c335e6 100644
--- a/src/libstate/lookup.cpp
+++ b/src/libstate/lookup.cpp
@@ -11,7 +11,7 @@
 
 namespace Botan {
 
-/**
+/*
 * Query if an algorithm exists
 */
 bool have_algorithm(const std::string& name)
@@ -29,7 +29,7 @@ bool have_algorithm(const std::string& name)
    return false;
    }
 
-/**
+/*
 * Query the block size of a cipher or hash
 */
 u32bit block_size_of(const std::string& name)
@@ -45,7 +45,7 @@ u32bit block_size_of(const std::string& name)
    throw Algorithm_Not_Found(name);
    }
 
-/**
+/*
 * Query the OUTPUT_LENGTH of a hash or MAC
 */
 u32bit output_length_of(const std::string& name)
@@ -61,7 +61,7 @@ u32bit output_length_of(const std::string& name)
    throw Algorithm_Not_Found(name);
    }
 
-/**
+/*
 * Check if a keylength is valid for this algo
 */
 bool valid_keylength_for(u32bit key_len, const std::string& name)
@@ -80,7 +80,7 @@ bool valid_keylength_for(u32bit key_len, const std::string& name)
    throw Algorithm_Not_Found(name);
    }
 
-/**
+/*
 * Query the MINIMUM_KEYLENGTH of an algorithm
 */
 u32bit min_keylength_of(const std::string& name)
@@ -99,7 +99,7 @@ u32bit min_keylength_of(const std::string& name)
    throw Algorithm_Not_Found(name);
    }
 
-/**
+/*
 * Query the MAXIMUM_KEYLENGTH of an algorithm
 */
 u32bit max_keylength_of(const std::string& name)
@@ -118,7 +118,7 @@ u32bit max_keylength_of(const std::string& name)
    throw Algorithm_Not_Found(name);
    }
 
-/**
+/*
 * Query the KEYLENGTH_MULTIPLE of an algorithm
 */
 u32bit keylength_multiple_of(const std::string& name)
@@ -137,7 +137,7 @@ u32bit keylength_multiple_of(const std::string& name)
    throw Algorithm_Not_Found(name);
    }
 
-/**
+/*
 * Get a cipher object
 */
 Keyed_Filter* get_cipher(const std::string& algo_spec,
@@ -156,7 +156,7 @@ Keyed_Filter* get_cipher(const std::string& algo_spec,
    throw Algorithm_Not_Found(algo_spec);
    }
 
-/**
+/*
 * Get a cipher object
 */
 Keyed_Filter* get_cipher(const std::string& algo_spec,
@@ -173,7 +173,7 @@ Keyed_Filter* get_cipher(const std::string& algo_spec,
    return cipher;
    }
 
-/**
+/*
 * Get a cipher object
 */
 Keyed_Filter* get_cipher(const std::string& algo_spec,
diff --git a/src/libstate/lookup.h b/src/libstate/lookup.h
index 5f10bb3f8..76e06b2de 100644
--- a/src/libstate/lookup.h
+++ b/src/libstate/lookup.h
@@ -61,8 +61,10 @@ retrieve_mac(const std::string& algo_spec)
 
 /**
 * Block cipher factory method.
+* @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)
    {
@@ -72,8 +74,10 @@ inline BlockCipher* get_block_cipher(const std::string& algo_spec)
 
 /**
 * Stream cipher factory method.
+* @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)
    {
@@ -83,8 +87,10 @@ inline StreamCipher* get_stream_cipher(const std::string& algo_spec)
 
 /**
 * Hash function factory method.
+* @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)
    {
@@ -94,8 +100,10 @@ inline HashFunction* get_hash(const std::string& algo_spec)
 
 /**
 * MAC factory method.
+* @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)
    {
@@ -105,8 +113,8 @@ inline MessageAuthenticationCode* get_mac(const std::string& algo_spec)
 
 /**
 * String to key algorithm factory method.
-* @param name the name of the desired string to key (S2K) algorithm
-* @return a pointer to the string to key algorithm object
+* @param algo_spec the name of the desired string to key (S2K) algorithm
+* @return pointer to the string to key algorithm object
 */
 BOTAN_DLL S2K* get_s2k(const std::string& algo_spec);
 
@@ -118,23 +126,23 @@ BOTAN_DLL S2K* get_s2k(const std::string& algo_spec);
 
 /**
 * Factory method for EME (message-encoding methods for encryption) objects
-* @param name the name of the EME to create
-* @return a pointer to the desired EME object
+* @param algo_spec the name of the EME to create
+* @return pointer to the desired EME object
 */
 BOTAN_DLL EME*  get_eme(const std::string& algo_spec);
 
 /**
 * Factory method for EMSA (message-encoding methods for signatures
 * with appendix) objects
-* @param name the name of the EME to create
-* @return a pointer to the desired EME object
+* @param algo_spec the name of the EME to create
+* @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 name the name of the KDF to create
-* @return a pointer to the desired KDF object
+* @param algo_spec the name of the KDF to create
+* @return pointer to the desired KDF object
 */
 BOTAN_DLL KDF*  get_kdf(const std::string& algo_spec);
 
@@ -150,12 +158,13 @@ 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& name,
+BOTAN_DLL Keyed_Filter* get_cipher(const std::string& algo_spec,
                                    const SymmetricKey& key,
                                    const InitializationVector& iv,
-                                   Cipher_Dir dir);
+                                   Cipher_Dir direction);
+
 /**
 * Factory method for general symmetric cipher filters.
 * @param algo_spec the name of the desired cipher
@@ -163,32 +172,36 @@ BOTAN_DLL Keyed_Filter* get_cipher(const std::string& name,
 * 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& name,
+BOTAN_DLL Keyed_Filter* get_cipher(const std::string& algo_spec,
                                    const SymmetricKey& key,
-                                   Cipher_Dir dir);
+                                   Cipher_Dir direction);
 
-/** Factory method for general symmetric cipher filters. No key will
-* be set in the filter.
+/**
+* Factory method for general symmetric cipher filters. No key will be
+* set in the filter.
+*
 * @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& name, Cipher_Dir dir);
+BOTAN_DLL Keyed_Filter* get_cipher(const std::string& algo_spec,
+                                   Cipher_Dir direction);
 
 /**
 * Check if an algorithm exists.
-* @param name the name of the algorithm to check for
+* @param algo_spec the name of the algorithm to check for
 * @return true if the algorithm exists, false otherwise
 */
 BOTAN_DLL bool have_algorithm(const std::string& algo_spec);
 
 /**
 * Check if a block cipher algorithm exists.
-* @param name the name of the algorithm to check for
+* @deprecated Call algorithm_factory() directly
+*
+* @param algo_spec the name of the algorithm to check for
 * @return true if the algorithm exists, false otherwise
 */
 inline bool have_block_cipher(const std::string& algo_spec)
@@ -199,7 +212,9 @@ inline bool have_block_cipher(const std::string& algo_spec)
 
 /**
 * Check if a stream cipher algorithm exists.
-* @param name the name of the algorithm to check for
+* @deprecated Call algorithm_factory() directly
+*
+* @param algo_spec the name of the algorithm to check for
 * @return true if the algorithm exists, false otherwise
 */
 inline bool have_stream_cipher(const std::string& algo_spec)
@@ -210,6 +225,8 @@ inline bool have_stream_cipher(const std::string& algo_spec)
 
 /**
 * Check if a hash algorithm exists.
+* @deprecated Call algorithm_factory() directly
+*
 * @param algo_spec the name of the algorithm to check for
 * @return true if the algorithm exists, false otherwise
 */
@@ -221,6 +238,8 @@ inline bool have_hash(const std::string& algo_spec)
 
 /**
 * Check if a MAC algorithm exists.
+* @deprecated Call algorithm_factory() directly
+*
 * @param algo_spec the name of the algorithm to check for
 * @return true if the algorithm exists, false otherwise
 */
@@ -236,46 +255,58 @@ inline bool have_mac(const std::string& algo_spec)
 
 /**
 * Find out the block size of a certain symmetric algorithm.
-* @param name the name of the algorithm
-* @return the block size of the specified algorithm
+* @deprecated Call algorithm_factory() directly
+*
+* @param algo_spec the name of the algorithm
+* @return block size of the specified algorithm
 */
 BOTAN_DLL u32bit block_size_of(const std::string& algo_spec);
 
 /**
 * Find out the output length of a certain symmetric algorithm.
-* @param name the name of the algorithm
-* @return the output length of the specified algorithm
+* @deprecated Call algorithm_factory() directly
+*
+* @param algo_spec the name of the algorithm
+* @return output length of the specified algorithm
 */
 BOTAN_DLL u32bit output_length_of(const std::string& algo_spec);
 
 /**
 * Find out the whether a certain key length is allowd for a given
 * symmetric algorithm.
+* @deprecated Call algorithm_factory() directly
+*
 * @param key_len the key length in question
-* @param name the name of the algorithm
+* @param algo_spec the name of the algorithm
 * @return true if the key length is valid for that algorithm, false otherwise
 */
-BOTAN_DLL bool valid_keylength_for(u32bit keylen,
+BOTAN_DLL bool valid_keylength_for(u32bit key_len,
                                    const std::string& algo_spec);
 
 /**
 * Find out the minimum key size of a certain symmetric algorithm.
-* @param name the name of the algorithm
-* @return the minimum key length of the specified algorithm
+* @deprecated Call algorithm_factory() directly
+*
+* @param algo_spec the name of the algorithm
+* @return minimum key length of the specified algorithm
 */
 BOTAN_DLL u32bit min_keylength_of(const std::string& algo_spec);
 
 /**
 * Find out the maximum key size of a certain symmetric algorithm.
-* @param name the name of the algorithm
-* @return the maximum key length of the specified algorithm
+* @deprecated Call algorithm_factory() directly
+*
+* @param algo_spec the name of the algorithm
+* @return maximum key length of the specified algorithm
 */
 BOTAN_DLL u32bit max_keylength_of(const std::string& algo_spec);
 
 /**
 * Find out the size any valid key is a multiple of for a certain algorithm.
-* @param name the name of the algorithm
-* @return the size any valid key is a multiple of
+* @deprecated Call algorithm_factory() directly
+*
+* @param algo_spec the name of the algorithm
+* @return size any valid key is a multiple of
 */
 BOTAN_DLL u32bit keylength_multiple_of(const std::string& algo_spec);
 
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.cpp b/src/libstate/scan_name.cpp
index eccb15565..7c2e4b28d 100644
--- a/src/libstate/scan_name.cpp
+++ b/src/libstate/scan_name.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * SCAN Name Abstraction
 * (C) 2008-2009 Jack Lloyd
 *
diff --git a/src/libstate/scan_name.h b/src/libstate/scan_name.h
index 4350dca86..3d11d54f6 100644
--- a/src/libstate/scan_name.h
+++ b/src/libstate/scan_name.h
@@ -1,4 +1,4 @@
-/**
+/*
 * SCAN Name Abstraction
 * (C) 2008 Jack Lloyd
 *
@@ -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/cbc_mac/cbc_mac.h b/src/mac/cbc_mac/cbc_mac.h
index 15026c0a9..772abd38f 100644
--- a/src/mac/cbc_mac/cbc_mac.h
+++ b/src/mac/cbc_mac/cbc_mac.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * CBC-MAC
 */
 class BOTAN_DLL CBC_MAC : public MessageAuthenticationCode
@@ -23,7 +23,10 @@ class BOTAN_DLL CBC_MAC : public MessageAuthenticationCode
       std::string name() const;
       MessageAuthenticationCode* clone() const;
 
-      CBC_MAC(BlockCipher* e);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      CBC_MAC(BlockCipher* cipher);
       ~CBC_MAC();
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/mac/cmac/cmac.h b/src/mac/cmac/cmac.h
index 8297e5ea1..b5f3eec1a 100644
--- a/src/mac/cmac/cmac.h
+++ b/src/mac/cmac/cmac.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* CMAC
+/**
+* CMAC, also known as OMAC1
 */
 class BOTAN_DLL CMAC : public MessageAuthenticationCode
    {
@@ -23,10 +23,18 @@ class BOTAN_DLL CMAC : public MessageAuthenticationCode
       std::string name() const;
       MessageAuthenticationCode* clone() const;
 
+      /**
+      * CMAC's polynomial doubling operation
+      * @param in the input
+      * @param polynomial the byte value of the polynomial
+      */
       static SecureVector<byte> poly_double(const MemoryRegion<byte>& in,
                                             byte polynomial);
 
-      CMAC(BlockCipher* e);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      CMAC(BlockCipher* cipher);
       ~CMAC();
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/mac/hmac/hmac.h b/src/mac/hmac/hmac.h
index 62bb69853..43a5d22a4 100644
--- a/src/mac/hmac/hmac.h
+++ b/src/mac/hmac/hmac.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * HMAC
 */
 class BOTAN_DLL HMAC : public MessageAuthenticationCode
@@ -23,6 +23,9 @@ class BOTAN_DLL HMAC : public MessageAuthenticationCode
       std::string name() const;
       MessageAuthenticationCode* clone() const;
 
+      /**
+      * @param hash the hash to use for HMACing
+      */
       HMAC(HashFunction* hash);
       ~HMAC() { delete hash; }
    private:
diff --git a/src/mac/mac.cpp b/src/mac/mac.cpp
index 04b259647..cb89e872a 100644
--- a/src/mac/mac.cpp
+++ b/src/mac/mac.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Message Authentication Code base class
 * (C) 1999-2008 Jack Lloyd
 *
@@ -9,7 +9,7 @@
 
 namespace Botan {
 
-/**
+/*
 * Default (deterministic) MAC verification operation
 */
 bool MessageAuthenticationCode::verify_mac(const byte mac[], u32bit length)
diff --git a/src/mac/mac.h b/src/mac/mac.h
index 7c73a2900..4518d91ad 100644
--- a/src/mac/mac.h
+++ b/src/mac/mac.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Base class for message authentiction codes
 * (C) 1999-2007 Jack Lloyd
 *
@@ -24,10 +24,10 @@ class BOTAN_DLL MessageAuthenticationCode : public BufferedComputation,
       /**
       * Verify a MAC.
       * @param in the MAC to verify as a byte array
-      * @param length the length of the byte array
+      * @param length the length of param in
       * @return true if the MAC is valid, false otherwise
       */
-      virtual bool verify_mac(const byte[], u32bit);
+      virtual bool verify_mac(const byte in[], u32bit length);
 
       /**
       * Get a new object representing the same algorithm as *this
@@ -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;
 
@@ -45,6 +45,12 @@ class BOTAN_DLL MessageAuthenticationCode : public BufferedComputation,
       */
       virtual void clear() = 0;
 
+      /**
+      * @param mac_len the output length of this MAC
+      * @param key_min the minimum key size
+      * @param key_max the maximum key size
+      * @param key_mod the modulo restriction on the key size
+      */
       MessageAuthenticationCode(u32bit mac_len,
                                 u32bit key_min,
                                 u32bit key_max = 0,
diff --git a/src/mac/ssl3mac/ssl3_mac.h b/src/mac/ssl3mac/ssl3_mac.h
index 828b072ed..019163ec8 100644
--- a/src/mac/ssl3mac/ssl3_mac.h
+++ b/src/mac/ssl3mac/ssl3_mac.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* SSL3-MAC
+/**
+* A MAC only used in SSLv3. Do not use elsewhere! Use HMAC instead.
 */
 class BOTAN_DLL SSL3_MAC : public MessageAuthenticationCode
    {
@@ -23,7 +23,10 @@ class BOTAN_DLL SSL3_MAC : public MessageAuthenticationCode
       std::string name() const;
       MessageAuthenticationCode* clone() const;
 
-      SSL3_MAC(HashFunction*);
+      /**
+      * @param hash the underlying hash to use
+      */
+      SSL3_MAC(HashFunction* hash);
       ~SSL3_MAC() { delete hash; }
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/mac/x919_mac/x919_mac.h b/src/mac/x919_mac/x919_mac.h
index abd149ecd..8432db7d1 100644
--- a/src/mac/x919_mac/x919_mac.h
+++ b/src/mac/x919_mac/x919_mac.h
@@ -23,7 +23,10 @@ class BOTAN_DLL ANSI_X919_MAC : public MessageAuthenticationCode
       std::string name() const;
       MessageAuthenticationCode* clone() const;
 
-      ANSI_X919_MAC(BlockCipher*);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      ANSI_X919_MAC(BlockCipher* cipher);
       ~ANSI_X919_MAC();
    private:
       void add_data(const byte[], u32bit);
diff --git a/src/math/bigint/bigint.cpp b/src/math/bigint/bigint.cpp
index b92cd359e..85d7c48ff 100644
--- a/src/math/bigint/bigint.cpp
+++ b/src/math/bigint/bigint.cpp
@@ -268,10 +268,12 @@ u32bit BigInt::bytes() const
 */
 u32bit BigInt::bits() const
    {
-   if(sig_words() == 0)
+   const u32bit words = sig_words();
+
+   if(words == 0)
       return 0;
 
-   u32bit full_words = sig_words() - 1, top_bits = MP_WORD_BITS;
+   u32bit full_words = words - 1, top_bits = MP_WORD_BITS;
    word top_word = word_at(full_words), mask = MP_WORD_TOP_BIT;
 
    while(top_bits && ((top_word & mask) == 0))
diff --git a/src/math/bigint/bigint.h b/src/math/bigint/bigint.h
index 3756da51f..2b95bfc90 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.
+     * Modulo operator
      * @param y the modulus to reduce this by
      */
      BigInt& operator%=(const BigInt& y);
 
      /**
-     * %= Operator
+     * Modulo 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
+     * Left shift operator
+     * @param shift the number of bits to shift this left by
      */
-     BigInt& operator<<=(u32bit y);
+     BigInt& operator<<=(u32bit shift);
 
      /**
-     * >>= Operator
-     * @param y the amount of bits to shift this right
+     * Right shift operator
+     * @param shift the number of bits to shift this right by
      */
-     BigInt& operator>>=(u32bit y);
+     BigInt& operator>>=(u32bit shift);
 
      /**
-     * ++ Operator
+     * Increment operator
      */
      BigInt& operator++() { return (*this += 1); }
 
      /**
-     * -- Operator
+     * Decrement operator
      */
      BigInt& operator--() { return (*this -= 1); }
 
      /**
-     * ++ Operator (postfix)
+     * Postfix increment operator
      */
      BigInt  operator++(int) { BigInt x = (*this); ++(*this); return x; }
 
      /**
-     * -- Operator (postfix)
+     * Postfix decrement operator
      */
      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,13 +164,13 @@ 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()); }
 
      /**
-     * Test if the integer is zero.
+     * Test if the integer is zero
      * @result true if the integer is zero, false otherwise
      */
      bool is_zero() const
@@ -220,28 +226,29 @@ 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); }
 
      /**
      * Return the integer as an unsigned 32bit-integer-value. If the
-     * value is negative OR to big to be stored in 32bits, this
+     * value is negative OR too big to be stored in a u32bit, this
      * function will throw an exception.
-     * @result a 32bit-integer
+     *
+     * @result unsigned 32 bit representation of this
      */
      u32bit to_u32bit() const;
 
      /**
-     * Tests if the sign of the integer is negative.
-     * @result true, if the integer has a negative sign,
+     * Tests if the sign of the integer is negative
+     * @result true, iff the integer has a negative sign
      */
      bool is_negative() const { return (sign() == Negative); }
 
      /**
-     * Tests if the sign of the integer is positive.
-     * @result true, if the integer has a positive sign,
+     * Tests if the sign of the integer is positive
+     * @result true, iff the integer has a positive sign
      */
      bool is_positive() const { return (sign() == Positive); }
 
@@ -252,13 +259,12 @@ class BOTAN_DLL BigInt
      Sign sign() const { return (signedness); }
 
      /**
-     * Return the opposite sign of the represented integer value
      * @result the opposite sign of the represented integer value
      */
      Sign reverse_sign() const;
 
      /**
-     * Flip (mutate) the sign of the integer to its opposite value
+     * Flip the sign of this BigInt
      */
      void flip_sign();
 
@@ -280,7 +286,7 @@ class BOTAN_DLL BigInt
      u32bit size() const { return get_reg().size(); }
 
      /**
-     * Give significant words of the represented integer value
+     * Return how many words we need to hold this value
      * @result significant words of the represented integer value
      */
      u32bit sig_words() const
@@ -294,19 +300,19 @@ class BOTAN_DLL BigInt
         }
 
      /**
-     * Give byte-length of the integer
-     * @result byte-length of the represented integer value
+     * Give byte length of the integer
+     * @result byte length of the represented integer value
      */
      u32bit bytes() const;
 
      /**
-     * Get the bit-length of the integer.
-     * @result bit-length of the represented integer value
+     * Get the bit length of the integer
+     * @result bit length of the represented integer value
      */
      u32bit bits() const;
 
      /**
-     * Return a pointer to the big integer word register.
+     * Return a pointer to the big integer word register
      * @result a pointer to the start of the internal register of
      * the integer value
      */
@@ -357,18 +363,25 @@ class BOTAN_DLL BigInt
 
      /**
      * Read integer value from a byte array (MemoryRegion<byte>)
-     * @param buf the BigInt value to compare to this.
+     * @param buf the array to load from
      */
      void binary_decode(const MemoryRegion<byte>& buf);
 
-     u32bit encoded_size(Base = Binary) const;
+     /**
+     * @param base the base to measure the size for
+     * @return size of this integer in base base
+     */
+     u32bit encoded_size(Base base = Binary) const;
 
      /**
-     @param rng a random number generator
-     @result a random integer between min and max
+     * @param rng a random number generator
+     * @param min the minimum value
+     * @param max the maximum value
+     * @return random integer between min and max
      */
      static BigInt random_integer(RandomNumberGenerator& rng,
-                                  const BigInt& min, const BigInt& max);
+                                  const BigInt& min,
+                                  const BigInt& max);
 
      /**
      * Encode the integer value from a BigInt to a SecureVector of bytes
@@ -389,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
@@ -408,10 +428,10 @@ class BOTAN_DLL BigInt
      static SecureVector<byte> encode_1363(const BigInt& n, u32bit bytes);
 
      /**
-     * Swap BigInt-value with given BigInt.
-     * @param bigint the BigInt to swap values with
+     * Swap this value with another
+     * @param other BigInt to swap values with
      */
-     void swap(BigInt& bigint);
+     void swap(BigInt& other);
 
      /**
      * Create empty BigInt
@@ -419,38 +439,34 @@ 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
+     * Copy Constructor
+     * @param other the BigInt to copy
      */
      BigInt(const BigInt& other);
 
      /**
-     * Assignment operator
-     */
-     BigInt& operator=(const BigInt&) = default;
-
-     /**
-     * Create BigInt from a string.
-     * If the string starts with 0x the rest of the string will be
-     * interpreted as hexadecimal digits.
-     * If the string starts with 0 and the second character is NOT
-     * an 'x' the string will be interpreted as octal digits.
-     * If the string starts with non-zero digit, it will be
-     * interpreted as a decimal number.
+     * Create BigInt from a string. If the string starts with 0x the
+     * rest of the string will be interpreted as hexadecimal digits.
+     * If the string starts with 0 and the second character is NOT an
+     * 'x' the string will be interpreted as octal digits. If the
+     * string starts with non-zero digit, it will be interpreted as a
+     * decimal number.
+     *
      * @param str the string to parse for an integer value
      */
      BigInt(const std::string& str);
 
      /**
      * 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);
 
@@ -464,14 +480,16 @@ class BOTAN_DLL BigInt
      /**
      * Create BigInt of specified size, all zeros
      * @param sign the sign
-     * @param n integer value
+     * @param n size of the internal register in words
      */
      BigInt(Sign sign, u32bit n);
 
      /**
      * Create a number of the specified type and size
-     * @param type the type of number to create
-     * @param n the size
+     * @param type the type of number to create. For Power2,
+     * will create the integer 2^n
+     * @param n a size/length parameter, interpretation depends upon
+     * the value of type
      */
      BigInt(NumberType type, u32bit n);
 
diff --git a/src/math/bigint/divide.h b/src/math/bigint/divide.h
index 9445b137b..36aed7854 100644
--- a/src/math/bigint/divide.h
+++ b/src/math/bigint/divide.h
@@ -12,7 +12,17 @@
 
 namespace Botan {
 
-void BOTAN_DLL divide(const BigInt&, const BigInt&, BigInt&, BigInt&);
+/**
+* BigInt Division
+* @param x an integer
+* @param y a non-zero integer
+* @param q will be set to x / y
+* @param r will be set to x % y
+*/
+void BOTAN_DLL divide(const BigInt& x,
+                      const BigInt& y,
+                      BigInt& q,
+                      BigInt& r);
 
 }
 
diff --git a/src/math/bigint/info.txt b/src/math/bigint/info.txt
index d5741943f..0511c2d8d 100644
--- a/src/math/bigint/info.txt
+++ b/src/math/bigint/info.txt
@@ -30,7 +30,7 @@ mp_shift.cpp
 <requires>
 alloc
 hex
-mp_amd64|mp_asm64|mp_ia32|mp_ia32_msvc|mp_generic
+mp_amd64|mp_amd64_msvc|mp_asm64|mp_ia32|mp_ia32_msvc|mp_generic
 monty_generic
 mulop_generic
 rng
diff --git a/src/math/bigint/mp_amd64_msvc/info.txt b/src/math/bigint/mp_amd64_msvc/info.txt
new file mode 100644
index 000000000..56ae05927
--- /dev/null
+++ b/src/math/bigint/mp_amd64_msvc/info.txt
@@ -0,0 +1,17 @@
+load_on dep
+
+mp_bits 64
+
+<header:internal>
+mp_asm.h
+mp_generic:mp_asmi.h
+</header:internal>
+
+<arch>
+amd64
+ia64
+</arch>
+
+<cc>
+msvc
+</cc>
diff --git a/src/math/bigint/mp_amd64_msvc/mp_asm.h b/src/math/bigint/mp_amd64_msvc/mp_asm.h
new file mode 100644
index 000000000..3acbe11bb
--- /dev/null
+++ b/src/math/bigint/mp_amd64_msvc/mp_asm.h
@@ -0,0 +1,61 @@
+/*
+* Multiply-Add for 64-bit MSVC
+* (C) 2010 Jack Lloyd
+*
+* Distributed under the terms of the Botan license
+*/
+
+#ifndef BOTAN_MP_ASM_H__
+#define BOTAN_MP_ASM_H__
+
+#include <botan/mp_types.h>
+#include <intrin.h>
+
+#if (BOTAN_MP_WORD_BITS != 64)
+   #error The mp_amd64_msvc module requires that BOTAN_MP_WORD_BITS == 64
+#endif
+
+#pragma intrinsic(_umul128)
+
+namespace Botan {
+
+extern "C" {
+
+/*
+* Word Multiply
+*/
+inline word word_madd2(word a, word b, word* c)
+   {
+   word hi, lo;
+   lo = _umul128(a, b, &hi);
+
+   lo += *c;
+   hi += (lo < *c); // carry?
+
+   *c = hi;
+   return lo;
+   }
+
+/*
+* Word Multiply/Add
+*/
+inline word word_madd3(word a, word b, word c, word* d)
+   {
+   word hi, lo;
+   lo = _umul128(a, b, &hi);
+
+   lo += c;
+   hi += (lo < c); // carry?
+
+   lo += *d;
+   hi += (lo < *d); // carry?
+
+   *d = hi;
+   return lo;
+   }
+
+}
+
+}
+
+#endif
diff --git a/src/math/bigint/mp_asm64/mp_asm.h b/src/math/bigint/mp_asm64/mp_asm.h
index c9159eaa7..b0906095d 100644
--- a/src/math/bigint/mp_asm64/mp_asm.h
+++ b/src/math/bigint/mp_asm64/mp_asm.h
@@ -47,7 +47,10 @@ namespace Botan {
 #elif defined(BOTAN_TARGET_ARCH_IS_MIPS64)
 
 #define BOTAN_WORD_MUL(a,b,z1,z0) do {                            \
-   asm("dmultu %2,%3" : "=h" (z0), "=l" (z1) : "r" (a), "r" (b)); \
+   typedef unsigned int uint128_t __attribute__((mode(TI)));      \
+   uint128_t r = (uint128_t)a * b;                                \
+   z0 = (r >> 64) & 0xFFFFFFFFFFFFFFFF;                           \
+   z1 = (r      ) & 0xFFFFFFFFFFFFFFFF;                           \
 } while(0);
 
 #else
diff --git a/src/math/numbertheory/def_powm.h b/src/math/numbertheory/def_powm.h
index 5b8a5a591..ce128b965 100644
--- a/src/math/numbertheory/def_powm.h
+++ b/src/math/numbertheory/def_powm.h
@@ -14,7 +14,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Fixed Window Exponentiator
 */
 class Fixed_Window_Exponentiator : public Modular_Exponentiator
@@ -36,7 +36,7 @@ class Fixed_Window_Exponentiator : public Modular_Exponentiator
       Power_Mod::Usage_Hints hints;
    };
 
-/*
+/**
 * Montgomery Exponentiator
 */
 class Montgomery_Exponentiator : public Modular_Exponentiator
diff --git a/src/math/numbertheory/numthry.h b/src/math/numbertheory/numthry.h
index 2d889a68a..9a1005413 100644
--- a/src/math/numbertheory/numthry.h
+++ b/src/math/numbertheory/numthry.h
@@ -14,8 +14,8 @@
 
 namespace Botan {
 
-/*
-* Fused Arithmetic Operations
+/**
+* Fused Arithmetic Operation
 */
 BigInt BOTAN_DLL mul_add(const BigInt&, const BigInt&, const BigInt&);
 BigInt BOTAN_DLL sub_mul(const BigInt&, const BigInt&, const BigInt&);
@@ -25,27 +25,70 @@ BigInt BOTAN_DLL sub_mul(const BigInt&, const BigInt&, const BigInt&);
 */
 inline BigInt abs(const BigInt& n) { return n.abs(); }
 
-void BOTAN_DLL divide(const BigInt&, const BigInt&, BigInt&, BigInt&);
-
+/**
+* Compute the greatest common divisor
+* @param x a positive integer
+* @param y a positive integer
+* @return gcd(x,y)
+*/
 BigInt BOTAN_DLL gcd(const BigInt& x, const BigInt& y);
+
+/**
+* Least common multiple
+* @param x a positive integer
+* @param y a positive integer
+* @return z, smallest integer such that z % x == 0 and z % y == 0
+*/
 BigInt BOTAN_DLL lcm(const BigInt& x, const BigInt& y);
 
-BigInt BOTAN_DLL square(const BigInt&);
-BigInt BOTAN_DLL inverse_mod(const BigInt&, const BigInt&);
-s32bit BOTAN_DLL jacobi(const BigInt&, const BigInt&);
+/**
+* @param x an integer
+* @return (x*x)
+*/
+BigInt BOTAN_DLL square(const BigInt& x);
+
+/**
+* Modular inversion
+* @param x a positive integer
+* @param modulus a positive integer
+* @return y st (x*y) % modulus == 1
+*/
+BigInt BOTAN_DLL inverse_mod(const BigInt& x,
+                             const BigInt& modulus);
 
+/**
+* Compute the Jacobi symbol. If n is prime, this is equivalent
+* to the Legendre symbol.
+* @see http://mathworld.wolfram.com/JacobiSymbol.html
+*
+* @param a is a non-negative integer
+* @param n is an odd integer > 1
+* @return (n / m)
+*/
+s32bit BOTAN_DLL jacobi(const BigInt& a,
+                        const BigInt& n);
+
+/**
+* Modular exponentation
+*/
 BigInt BOTAN_DLL power_mod(const BigInt&, const BigInt&, const BigInt&);
 
-/*
-* Compute the square root of x modulo a prime
-* using the Shanks-Tonnelli algorithm
+/**
+* Compute the square root of x modulo a prime using the
+* Shanks-Tonnelli algorithm
+*
+* @param x the input
+* @param p the prime
+* @return y such that (y*y)%p == x, or -1 if no such integer
 */
 BigInt BOTAN_DLL ressol(const BigInt& x, const BigInt& p);
 
-/*
-* Utility Functions
+/**
+* @param x an integer
+* @return count of the zero bits in x, or, equivalently, the largest
+* value of n such that 2^n divides x evently
 */
-u32bit BOTAN_DLL low_zero_bits(const BigInt&);
+u32bit BOTAN_DLL low_zero_bits(const BigInt& x);
 
 /*
 * Primality Testing
diff --git a/src/math/numbertheory/point_gfp.h b/src/math/numbertheory/point_gfp.h
index 0708493fe..5b3e32c7d 100644
--- a/src/math/numbertheory/point_gfp.h
+++ b/src/math/numbertheory/point_gfp.h
@@ -15,6 +15,10 @@
 
 namespace Botan {
 
+/**
+* Exception thrown if you try to convert a zero point to an affine
+* coordinate
+*/
 struct BOTAN_DLL Illegal_Transformation : public Exception
    {
    Illegal_Transformation(const std::string& err =
@@ -22,6 +26,9 @@ struct BOTAN_DLL Illegal_Transformation : public Exception
       Exception(err) {}
    };
 
+/**
+* Exception thrown if some form of illegal point is decoded
+*/
 struct BOTAN_DLL Illegal_Point : public Exception
    {
    Illegal_Point(const std::string& err = "Malformed ECP point detected") :
diff --git a/src/math/numbertheory/pow_mod.h b/src/math/numbertheory/pow_mod.h
index 7b92f0ec4..1a60ca05f 100644
--- a/src/math/numbertheory/pow_mod.h
+++ b/src/math/numbertheory/pow_mod.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Modular Exponentiator Interface
 */
 class BOTAN_DLL Modular_Exponentiator
@@ -25,7 +25,7 @@ class BOTAN_DLL Modular_Exponentiator
       virtual ~Modular_Exponentiator() {}
    };
 
-/*
+/**
 * Modular Exponentiator Proxy
 */
 class BOTAN_DLL Power_Mod
@@ -67,7 +67,7 @@ class BOTAN_DLL Power_Mod
       Usage_Hints hints;
    };
 
-/*
+/**
 * Fixed Exponent Modular Exponentiator Proxy
 */
 class BOTAN_DLL Fixed_Exponent_Power_Mod : public Power_Mod
@@ -81,7 +81,7 @@ class BOTAN_DLL Fixed_Exponent_Power_Mod : public Power_Mod
                                Usage_Hints = NO_HINTS);
    };
 
-/*
+/**
 * Fixed Base Modular Exponentiator Proxy
 */
 class BOTAN_DLL Fixed_Base_Power_Mod : public Power_Mod
diff --git a/src/math/numbertheory/reducer.h b/src/math/numbertheory/reducer.h
index c121f1499..861983ef0 100644
--- a/src/math/numbertheory/reducer.h
+++ b/src/math/numbertheory/reducer.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Modular Reducer
 */
 class BOTAN_DLL Modular_Reducer
@@ -24,18 +24,25 @@ class BOTAN_DLL Modular_Reducer
 
       /**
       * Multiply mod p
+      * @param x
+      * @param y
+      * @return (x * y) % p
       */
       BigInt multiply(const BigInt& x, const BigInt& y) const
          { return reduce(x * y); }
 
       /**
       * Square mod p
+      * @param x
+      * @return (x * x) % p
       */
       BigInt square(const BigInt& x) const
          { return reduce(Botan::square(x)); }
 
       /**
       * Cube mod p
+      * @param x
+      * @return (x * x * x) % p
       */
       BigInt cube(const BigInt& x) const
          { return multiply(x, this->square(x)); }
diff --git a/src/pbe/get_pbe.h b/src/pbe/get_pbe.h
index 04eda6696..73c53497c 100644
--- a/src/pbe/get_pbe.h
+++ b/src/pbe/get_pbe.h
@@ -16,17 +16,18 @@ namespace Botan {
 /**
 * Factory function for PBEs.
 * @param algo_spec the name of the PBE algorithm to retrieve
-* @return a pointer to a PBE with randomly created parameters
+* @return pointer to a PBE with randomly created parameters
 */
-BOTAN_DLL PBE* get_pbe(const std::string&);
+BOTAN_DLL PBE* get_pbe(const std::string& algo_spec);
 
 /**
 * Factory function for PBEs.
 * @param pbe_oid the oid of the desired PBE
 * @param params a DataSource providing the DER encoded parameters to use
-* @return a pointer to the PBE with the specified parameters
+* @return pointer to the PBE with the specified parameters
 */
-BOTAN_DLL PBE* get_pbe(const OID&, DataSource&);
+BOTAN_DLL PBE* get_pbe(const OID& pbe_oid,
+                       DataSource& params);
 
 }
 
diff --git a/src/pbe/pbes1/pbes1.cpp b/src/pbe/pbes1/pbes1.cpp
index 36cfaa6b4..a3e08d679 100644
--- a/src/pbe/pbes1/pbes1.cpp
+++ b/src/pbe/pbes1/pbes1.cpp
@@ -93,7 +93,7 @@ void PBE_PKCS5v15::set_key(const std::string& passphrase)
 */
 void PBE_PKCS5v15::new_params(RandomNumberGenerator& rng)
    {
-   iterations = 2048;
+   iterations = 10000;
    salt.resize(8);
    rng.randomize(salt, salt.size());
    }
diff --git a/src/pbe/pbes1/pbes1.h b/src/pbe/pbes1/pbes1.h
index 2e1855dc2..d50c01f53 100644
--- a/src/pbe/pbes1/pbes1.h
+++ b/src/pbe/pbes1/pbes1.h
@@ -15,8 +15,8 @@
 
 namespace Botan {
 
-/*
-* PKCS#5 v1.5 PBE
+/**
+* PKCS #5 v1.5 PBE
 */
 class BOTAN_DLL PBE_PKCS5v15 : public PBE
    {
@@ -25,9 +25,14 @@ class BOTAN_DLL PBE_PKCS5v15 : public PBE
       void start_msg();
       void end_msg();
 
+      /**
+      * @param cipher the block cipher to use (DES or RC2)
+      * @param hash the hash function to use
+      * @param direction are we encrypting or decrypting
+      */
       PBE_PKCS5v15(BlockCipher* cipher,
                    HashFunction* hash,
-                   Cipher_Dir);
+                   Cipher_Dir direction);
 
       ~PBE_PKCS5v15();
    private:
diff --git a/src/pbe/pbes2/pbes2.cpp b/src/pbe/pbes2/pbes2.cpp
index 63772263f..1ac16af8d 100644
--- a/src/pbe/pbes2/pbes2.cpp
+++ b/src/pbe/pbes2/pbes2.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * PKCS #5 PBES2
 * (C) 1999-2008 Jack Lloyd
 *
@@ -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,22 +92,22 @@ 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)
    {
-   iterations = 2048;
+   iterations = 10000;
    key_length = block_cipher->MAXIMUM_KEYLENGTH;
 
-   salt.resize(8);
+   salt.resize(12);
    rng.randomize(salt, salt.size());
 
    iv.resize(block_cipher->BLOCK_SIZE);
    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 fc460a228..f24d572d0 100644
--- a/src/pbe/pbes2/pbes2.h
+++ b/src/pbe/pbes2/pbes2.h
@@ -15,20 +15,33 @@
 
 namespace Botan {
 
-/*
-* PKCS#5 v2.0 PBE
+/**
+* PKCS #5 v2.0 PBE
 */
 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/pk_pad/eme.h b/src/pk_pad/eme.h
index 321c1d01e..02b8208ef 100644
--- a/src/pk_pad/eme.h
+++ b/src/pk_pad/eme.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Encoding Method for Encryption
 */
 class BOTAN_DLL EME
diff --git a/src/pk_pad/eme1/eme1.h b/src/pk_pad/eme1/eme1.h
index 4df5c5f1c..d00eeeeb9 100644
--- a/src/pk_pad/eme1/eme1.h
+++ b/src/pk_pad/eme1/eme1.h
@@ -14,8 +14,8 @@
 
 namespace Botan {
 
-/*
-* EME1
+/**
+* EME1, aka OAEP
 */
 class BOTAN_DLL EME1 : public EME
    {
diff --git a/src/pk_pad/eme_pkcs/eme_pkcs.h b/src/pk_pad/eme_pkcs/eme_pkcs.h
index 1aeedf5d7..450d668d7 100644
--- a/src/pk_pad/eme_pkcs/eme_pkcs.h
+++ b/src/pk_pad/eme_pkcs/eme_pkcs.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* EME_PKCS1v15
+/**
+* EME from PKCS #1 v1.5
 */
 class BOTAN_DLL EME_PKCS1v15 : public EME
    {
diff --git a/src/pk_pad/emsa.h b/src/pk_pad/emsa.h
index 8b19d3cb2..6d01beb7f 100644
--- a/src/pk_pad/emsa.h
+++ b/src/pk_pad/emsa.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Encoding Method for Signatures, Appendix
 */
 class BOTAN_DLL EMSA
diff --git a/src/pk_pad/emsa1/emsa1.h b/src/pk_pad/emsa1/emsa1.h
index d86020966..28d856525 100644
--- a/src/pk_pad/emsa1/emsa1.h
+++ b/src/pk_pad/emsa1/emsa1.h
@@ -13,8 +13,9 @@
 
 namespace Botan {
 
-/*
-* EMSA1
+/**
+* EMSA1 from IEEE 1363
+* Essentially, sign the hash directly
 */
 class BOTAN_DLL EMSA1 : public EMSA
    {
diff --git a/src/pk_pad/emsa2/emsa2.h b/src/pk_pad/emsa2/emsa2.h
index 7efc80873..bda34fbd1 100644
--- a/src/pk_pad/emsa2/emsa2.h
+++ b/src/pk_pad/emsa2/emsa2.h
@@ -13,8 +13,9 @@
 
 namespace Botan {
 
-/*
-* EMSA2
+/**
+* EMSA2 from IEEE 1363
+* Useful for Rabin-Williams
 */
 class BOTAN_DLL EMSA2 : public EMSA
    {
diff --git a/src/pk_pad/emsa3/emsa3.h b/src/pk_pad/emsa3/emsa3.h
index c4a3d658b..1e080aab6 100644
--- a/src/pk_pad/emsa3/emsa3.h
+++ b/src/pk_pad/emsa3/emsa3.h
@@ -14,7 +14,7 @@
 namespace Botan {
 
 /**
-* EMSA3
+* EMSA3 from IEEE 1363
 * aka PKCS #1 v1.5 signature padding
 * aka PKCS #1 block type 1
 */
diff --git a/src/pk_pad/emsa4/emsa4.h b/src/pk_pad/emsa4/emsa4.h
index 9e37684f5..6315c424e 100644
--- a/src/pk_pad/emsa4/emsa4.h
+++ b/src/pk_pad/emsa4/emsa4.h
@@ -14,8 +14,8 @@
 
 namespace Botan {
 
-/*
-* EMSA4
+/**
+* EMSA4 aka PSS-R
 */
 class BOTAN_DLL EMSA4 : public EMSA
    {
diff --git a/src/pk_pad/emsa_raw/emsa_raw.h b/src/pk_pad/emsa_raw/emsa_raw.h
index 5f2eaa2fe..ab27877a6 100644
--- a/src/pk_pad/emsa_raw/emsa_raw.h
+++ b/src/pk_pad/emsa_raw/emsa_raw.h
@@ -12,8 +12,9 @@
 
 namespace Botan {
 
-/*
-* EMSA-Raw
+/**
+* EMSA-Raw - sign inputs directly
+* Don't use this unless you know what you are doing.
 */
 class BOTAN_DLL EMSA_Raw : public EMSA
    {
diff --git a/src/pk_pad/hash_id/hash_id.cpp b/src/pk_pad/hash_id/hash_id.cpp
index c83ad87ac..203c27f14 100644
--- a/src/pk_pad/hash_id/hash_id.cpp
+++ b/src/pk_pad/hash_id/hash_id.cpp
@@ -10,45 +10,45 @@
 
 namespace Botan {
 
-namespace PKCS_IDS {
+namespace {
 
-const byte MD2_ID[] = {
+const byte MD2_PKCS_ID[] = {
 0x30, 0x20, 0x30, 0x0C, 0x06, 0x08, 0x2A, 0x86, 0x48, 0x86,
 0xF7, 0x0D, 0x02, 0x02, 0x05, 0x00, 0x04, 0x10 };
 
-const byte MD5_ID[] = {
+const byte MD5_PKCS_ID[] = {
 0x30, 0x20, 0x30, 0x0C, 0x06, 0x08, 0x2A, 0x86, 0x48, 0x86,
 0xF7, 0x0D, 0x02, 0x05, 0x05, 0x00, 0x04, 0x10 };
 
-const byte RIPEMD_128_ID[] = {
+const byte RIPEMD_128_PKCS_ID[] = {
 0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2B, 0x24, 0x03, 0x02,
 0x02, 0x05, 0x00, 0x04, 0x14 };
 
-const byte RIPEMD_160_ID[] = {
+const byte RIPEMD_160_PKCS_ID[] = {
 0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2B, 0x24, 0x03, 0x02,
 0x01, 0x05, 0x00, 0x04, 0x14 };
 
-const byte SHA_160_ID[] = {
+const byte SHA_160_PKCS_ID[] = {
 0x30, 0x21, 0x30, 0x09, 0x06, 0x05, 0x2B, 0x0E, 0x03, 0x02,
 0x1A, 0x05, 0x00, 0x04, 0x14 };
 
-const byte SHA_224_ID[] = {
+const byte SHA_224_PKCS_ID[] = {
 0x30, 0x2D, 0x30, 0x0D, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01,
 0x65, 0x03, 0x04, 0x02, 0x04, 0x05, 0x00, 0x04, 0x1C };
 
-const byte SHA_256_ID[] = {
+const byte SHA_256_PKCS_ID[] = {
 0x30, 0x31, 0x30, 0x0D, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01,
 0x65, 0x03, 0x04, 0x02, 0x01, 0x05, 0x00, 0x04, 0x20 };
 
-const byte SHA_384_ID[] = {
+const byte SHA_384_PKCS_ID[] = {
 0x30, 0x41, 0x30, 0x0D, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01,
 0x65, 0x03, 0x04, 0x02, 0x02, 0x05, 0x00, 0x04, 0x30 };
 
-const byte SHA_512_ID[] = {
+const byte SHA_512_PKCS_ID[] = {
 0x30, 0x51, 0x30, 0x0D, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01,
 0x65, 0x03, 0x04, 0x02, 0x03, 0x05, 0x00, 0x04, 0x40 };
 
-const byte TIGER_ID[] = {
+const byte TIGER_PKCS_ID[] = {
 0x30, 0x29, 0x30, 0x0D, 0x06, 0x09, 0x2B, 0x06, 0x01, 0x04,
 0x01, 0xDA, 0x47, 0x0C, 0x02, 0x05, 0x00, 0x04, 0x18 };
 
@@ -63,29 +63,30 @@ MemoryVector<byte> pkcs_hash_id(const std::string& name)
    {
    MemoryVector<byte> out;
 
+   // Special case for SSL/TLS RSA signatures
    if(name == "Parallel(MD5,SHA-160)")
       return out;
 
    if(name == "MD2")
-      out.set(PKCS_IDS::MD2_ID, sizeof(PKCS_IDS::MD2_ID));
+      out.set(MD2_PKCS_ID, sizeof(MD2_PKCS_ID));
    else if(name == "MD5")
-      out.set(PKCS_IDS::MD5_ID, sizeof(PKCS_IDS::MD5_ID));
+      out.set(MD5_PKCS_ID, sizeof(MD5_PKCS_ID));
    else if(name == "RIPEMD-128")
-      out.set(PKCS_IDS::RIPEMD_128_ID, sizeof(PKCS_IDS::RIPEMD_128_ID));
+      out.set(RIPEMD_128_PKCS_ID, sizeof(RIPEMD_128_PKCS_ID));
    else if(name == "RIPEMD-160")
-      out.set(PKCS_IDS::RIPEMD_160_ID, sizeof(PKCS_IDS::RIPEMD_160_ID));
+      out.set(RIPEMD_160_PKCS_ID, sizeof(RIPEMD_160_PKCS_ID));
    else if(name == "SHA-160")
-      out.set(PKCS_IDS::SHA_160_ID, sizeof(PKCS_IDS::SHA_160_ID));
+      out.set(SHA_160_PKCS_ID, sizeof(SHA_160_PKCS_ID));
    else if(name == "SHA-224")
-      out.set(PKCS_IDS::SHA_224_ID, sizeof(PKCS_IDS::SHA_224_ID));
+      out.set(SHA_224_PKCS_ID, sizeof(SHA_224_PKCS_ID));
    else if(name == "SHA-256")
-      out.set(PKCS_IDS::SHA_256_ID, sizeof(PKCS_IDS::SHA_256_ID));
+      out.set(SHA_256_PKCS_ID, sizeof(SHA_256_PKCS_ID));
    else if(name == "SHA-384")
-      out.set(PKCS_IDS::SHA_384_ID, sizeof(PKCS_IDS::SHA_384_ID));
+      out.set(SHA_384_PKCS_ID, sizeof(SHA_384_PKCS_ID));
    else if(name == "SHA-512")
-      out.set(PKCS_IDS::SHA_512_ID, sizeof(PKCS_IDS::SHA_512_ID));
+      out.set(SHA_512_PKCS_ID, sizeof(SHA_512_PKCS_ID));
    else if(name == "Tiger(24,3)")
-      out.set(PKCS_IDS::TIGER_ID, sizeof(PKCS_IDS::TIGER_ID));
+      out.set(TIGER_PKCS_ID, sizeof(TIGER_PKCS_ID));
 
    if(out.size())
       return out;
diff --git a/src/pubkey/blinding.h b/src/pubkey/blinding.h
index 03c9043dd..712030e4d 100644
--- a/src/pubkey/blinding.h
+++ b/src/pubkey/blinding.h
@@ -13,7 +13,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Blinding Function Object
 */
 class BOTAN_DLL Blinder
diff --git a/src/pubkey/dh/dh.h b/src/pubkey/dh/dh.h
index 738b3f9c4..88b57922d 100644
--- a/src/pubkey/dh/dh.h
+++ b/src/pubkey/dh/dh.h
@@ -56,7 +56,7 @@ class BOTAN_DLL DH_PrivateKey : public DH_PublicKey,
       * Load a DH private key
       * @param alg_id the algorithm id
       * @param key_bits the subject public key
-      * @rng a random number generator
+      * @param rng a random number generator
       */
       DH_PrivateKey(const AlgorithmIdentifier& alg_id,
                     const MemoryRegion<byte>& key_bits,
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.cpp b/src/pubkey/dl_group/dl_group.cpp
index 22c72480e..cd75e5796 100644
--- a/src/pubkey/dl_group/dl_group.cpp
+++ b/src/pubkey/dl_group/dl_group.cpp
@@ -55,31 +55,32 @@ DL_Group::DL_Group(RandomNumberGenerator& rng,
       q = (p - 1) / 2;
       g = 2;
       }
-   else if(type == Prime_Subgroup || type == DSA_Kosherizer)
+   else if(type == Prime_Subgroup)
       {
-      if(type == Prime_Subgroup)
-         {
-         if(!qbits)
-            qbits = 2 * dl_work_factor(pbits);
-
-         q = random_prime(rng, qbits);
-         BigInt X;
-         while(p.bits() != pbits || !check_prime(p, rng))
-            {
-            X.randomize(rng, pbits);
-            p = X - (X % (2*q) - 1);
-            }
-         }
-      else
+      if(!qbits)
+         qbits = 2 * dl_work_factor(pbits);
+
+      q = random_prime(rng, qbits);
+      BigInt X;
+      while(p.bits() != pbits || !check_prime(p, rng))
          {
-         qbits = qbits ? qbits : ((pbits == 1024) ? 160 : 256);
-         generate_dsa_primes(rng,
-                             global_state().algorithm_factory(),
-                             p, q, pbits, qbits);
+         X.randomize(rng, pbits);
+         p = X - (X % (2*q) - 1);
          }
 
       g = make_dsa_generator(p, q);
       }
+   else if(type == DSA_Kosherizer)
+      {
+      qbits = qbits ? qbits : ((pbits <= 1024) ? 160 : 256);
+
+      generate_dsa_primes(rng,
+                          global_state().algorithm_factory(),
+                          p, q,
+                          pbits, qbits);
+
+      g = make_dsa_generator(p, q);
+      }
 
    initialized = true;
    }
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/dlies/dlies.h b/src/pubkey/dlies/dlies.h
index fd2cefe4a..ad8f36b40 100644
--- a/src/pubkey/dlies/dlies.h
+++ b/src/pubkey/dlies/dlies.h
@@ -14,7 +14,7 @@
 
 namespace Botan {
 
-/*
+/**
 * DLIES Encryption
 */
 class BOTAN_DLL DLIES_Encryptor : public PK_Encryptor
@@ -41,7 +41,7 @@ class BOTAN_DLL DLIES_Encryptor : public PK_Encryptor
       u32bit mac_keylen;
    };
 
-/*
+/**
 * DLIES Decryption
 */
 class BOTAN_DLL DLIES_Decryptor : public PK_Decryptor
diff --git a/src/pubkey/dsa/dsa.h b/src/pubkey/dsa/dsa.h
index 8121cfbbc..65b6edd98 100644
--- a/src/pubkey/dsa/dsa.h
+++ b/src/pubkey/dsa/dsa.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * DSA Public Key
 */
 class BOTAN_DLL DSA_PublicKey : public virtual DL_Scheme_PublicKey
@@ -39,7 +39,7 @@ class BOTAN_DLL DSA_PublicKey : public virtual DL_Scheme_PublicKey
       DSA_PublicKey() {}
    };
 
-/*
+/**
 * DSA Private Key
 */
 class BOTAN_DLL DSA_PrivateKey : public DSA_PublicKey,
@@ -57,6 +57,9 @@ class BOTAN_DLL DSA_PrivateKey : public DSA_PublicKey,
       bool check_key(RandomNumberGenerator& rng, bool strong) const;
    };
 
+/**
+* Object that can create a DSA signature
+*/
 class BOTAN_DLL DSA_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -75,6 +78,9 @@ class BOTAN_DLL DSA_Signature_Operation : public PK_Ops::Signature
       Modular_Reducer mod_q;
    };
 
+/**
+* Object that can verify a DSA signature
+*/
 class BOTAN_DLL DSA_Verification_Operation : public PK_Ops::Verification
    {
    public:
diff --git a/src/pubkey/ec_dompar/ec_dompar.h b/src/pubkey/ec_dompar/ec_dompar.h
index 15143373a..546624bf6 100644
--- a/src/pubkey/ec_dompar/ec_dompar.h
+++ b/src/pubkey/ec_dompar/ec_dompar.h
@@ -25,6 +25,9 @@ enum EC_Domain_Params_Encoding {
    EC_DOMPAR_ENC_OID = 2
 };
 
+/**
+* Class representing an elliptic curve
+*/
 class BOTAN_DLL EC_Domain_Params
    {
    public:
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 19621f2ca..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); }
@@ -75,7 +75,8 @@ class BOTAN_DLL ECDH_PrivateKey : public ECDH_PublicKey,
 
       /**
       * Generate a new private key
-      * @param the domain parameters to used for this key
+      * @param rng a random number generator
+      * @param domain parameters to used for this key
       */
       ECDH_PrivateKey(RandomNumberGenerator& rng,
                       const EC_Domain_Params& domain) :
diff --git a/src/pubkey/ecdsa/ecdsa.h b/src/pubkey/ecdsa/ecdsa.h
index 62bd007f9..7e7d85ab8 100644
--- a/src/pubkey/ecdsa/ecdsa.h
+++ b/src/pubkey/ecdsa/ecdsa.h
@@ -72,7 +72,8 @@ class BOTAN_DLL ECDSA_PrivateKey : public ECDSA_PublicKey,
 
       /**
       * Generate a new private key
-      * @param the domain parameters to used for this key
+      * @param rng a random number generator
+      * @param domain parameters to used for this key
       */
       ECDSA_PrivateKey(RandomNumberGenerator& rng,
                        const EC_Domain_Params& domain) :
@@ -83,12 +84,16 @@ class BOTAN_DLL ECDSA_PrivateKey : public ECDSA_PublicKey,
       * @param domain parameters
       * @param x the private key
       */
-      ECDSA_PrivateKey(const EC_Domain_Params& domain, const BigInt& x) :
+      ECDSA_PrivateKey(const EC_Domain_Params& domain,
+                       const BigInt& x) :
          EC_PrivateKey(domain, x) {}
 
       bool check_key(RandomNumberGenerator& rng, bool) const;
    };
 
+/**
+* ECDSA signature operation
+*/
 class BOTAN_DLL ECDSA_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -108,6 +113,9 @@ class BOTAN_DLL ECDSA_Signature_Operation : public PK_Ops::Signature
       Modular_Reducer mod_order;
    };
 
+/**
+* ECDSA verification operation
+*/
 class BOTAN_DLL ECDSA_Verification_Operation : public PK_Ops::Verification
    {
    public:
diff --git a/src/pubkey/elgamal/elgamal.h b/src/pubkey/elgamal/elgamal.h
index 143b417ec..f9b52c7b8 100644
--- a/src/pubkey/elgamal/elgamal.h
+++ b/src/pubkey/elgamal/elgamal.h
@@ -16,7 +16,7 @@
 
 namespace Botan {
 
-/*
+/**
 * ElGamal Public Key
 */
 class BOTAN_DLL ElGamal_PublicKey : public virtual DL_Scheme_PublicKey
@@ -37,7 +37,7 @@ class BOTAN_DLL ElGamal_PublicKey : public virtual DL_Scheme_PublicKey
       ElGamal_PublicKey() {}
    };
 
-/*
+/**
 * ElGamal Private Key
 */
 class BOTAN_DLL ElGamal_PrivateKey : public ElGamal_PublicKey,
@@ -55,6 +55,9 @@ class BOTAN_DLL ElGamal_PrivateKey : public ElGamal_PublicKey,
                          const BigInt& priv_key = 0);
    };
 
+/**
+* ElGamal encryption operation
+*/
 class BOTAN_DLL ElGamal_Encryption_Operation : public PK_Ops::Encryption
    {
    public:
@@ -70,6 +73,9 @@ class BOTAN_DLL ElGamal_Encryption_Operation : public PK_Ops::Encryption
       Modular_Reducer mod_p;
    };
 
+/**
+* ElGamal decryption operation
+*/
 class BOTAN_DLL ElGamal_Decryption_Operation : public PK_Ops::Decryption
    {
    public:
diff --git a/src/pubkey/gost_3410/gost_3410.h b/src/pubkey/gost_3410/gost_3410.h
index 36fa2912d..9d6a15386 100644
--- a/src/pubkey/gost_3410/gost_3410.h
+++ b/src/pubkey/gost_3410/gost_3410.h
@@ -16,7 +16,7 @@
 namespace Botan {
 
 /**
-* This class represents GOST_3410 Public Keys.
+* GOST-34.10 Public Key
 */
 class BOTAN_DLL GOST_3410_PublicKey : public virtual EC_PublicKey
    {
@@ -65,7 +65,7 @@ class BOTAN_DLL GOST_3410_PublicKey : public virtual EC_PublicKey
    };
 
 /**
-* This class represents GOST_3410 Private Keys
+* GOST-34.10 Private Key
 */
 class BOTAN_DLL GOST_3410_PrivateKey : public GOST_3410_PublicKey,
                                        public EC_PrivateKey
@@ -78,7 +78,8 @@ class BOTAN_DLL GOST_3410_PrivateKey : public GOST_3410_PublicKey,
 
       /**
       * Generate a new private key
-      * @param the domain parameters to used for this key
+      * @param rng a random number generator
+      * @param domain parameters to used for this key
       */
       GOST_3410_PrivateKey(RandomNumberGenerator& rng,
                            const EC_Domain_Params& domain) :
@@ -96,6 +97,9 @@ class BOTAN_DLL GOST_3410_PrivateKey : public GOST_3410_PublicKey,
          { return EC_PublicKey::algorithm_identifier(); }
    };
 
+/**
+* GOST-34.10 signature operation
+*/
 class BOTAN_DLL GOST_3410_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -114,6 +118,9 @@ class BOTAN_DLL GOST_3410_Signature_Operation : public PK_Ops::Signature
       const BigInt& x;
    };
 
+/**
+* GOST-34.10 verification operation
+*/
 class BOTAN_DLL GOST_3410_Verification_Operation : public PK_Ops::Verification
    {
    public:
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/nr/nr.h b/src/pubkey/nr/nr.h
index bd125ab92..cd12001ad 100644
--- a/src/pubkey/nr/nr.h
+++ b/src/pubkey/nr/nr.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Nyberg-Rueppel Public Key
 */
 class BOTAN_DLL NR_PublicKey : public virtual DL_Scheme_PublicKey
@@ -37,7 +37,7 @@ class BOTAN_DLL NR_PublicKey : public virtual DL_Scheme_PublicKey
       NR_PublicKey() {}
    };
 
-/*
+/**
 * Nyberg-Rueppel Private Key
 */
 class BOTAN_DLL NR_PrivateKey : public NR_PublicKey,
@@ -55,6 +55,9 @@ class BOTAN_DLL NR_PrivateKey : public NR_PublicKey,
                     const BigInt& x = 0);
    };
 
+/**
+* Nyberg-Rueppel signature operation
+*/
 class BOTAN_DLL NR_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -73,6 +76,9 @@ class BOTAN_DLL NR_Signature_Operation : public PK_Ops::Signature
       Modular_Reducer mod_q;
    };
 
+/**
+* Nyberg-Rueppel verification operation
+*/
 class BOTAN_DLL NR_Verification_Operation : public PK_Ops::Verification
    {
    public:
diff --git a/src/pubkey/pk_keys.cpp b/src/pubkey/pk_keys.cpp
index b93158558..c19c676ab 100644
--- a/src/pubkey/pk_keys.cpp
+++ b/src/pubkey/pk_keys.cpp
@@ -6,6 +6,7 @@
 */
 
 #include <botan/pk_keys.h>
+#include <botan/der_enc.h>
 #include <botan/oids.h>
 
 namespace Botan {
diff --git a/src/pubkey/pk_keys.h b/src/pubkey/pk_keys.h
index da73db0ee..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&, bool) 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;
 
@@ -73,7 +73,11 @@ class BOTAN_DLL Public_Key
 
       virtual ~Public_Key() {}
    protected:
-      virtual void load_check(RandomNumberGenerator&) const;
+      /**
+      * Self-test after loading a key
+      * @param rng a random number generator
+      */
+      virtual void load_check(RandomNumberGenerator& rng) const;
    };
 
 /**
@@ -95,8 +99,17 @@ class BOTAN_DLL Private_Key : public virtual Public_Key
          { return algorithm_identifier(); }
 
    protected:
-      void load_check(RandomNumberGenerator&) const;
-      void gen_check(RandomNumberGenerator&) const;
+      /**
+      * Self-test after loading a key
+      * @param rng a random number generator
+      */
+      void load_check(RandomNumberGenerator& rng) const;
+
+      /**
+      * Self-test after generating a key
+      * @param rng a random number generator
+      */
+      void gen_check(RandomNumberGenerator& rng) const;
    };
 
 /**
@@ -105,6 +118,9 @@ class BOTAN_DLL Private_Key : public virtual Public_Key
 class BOTAN_DLL PK_Key_Agreement_Key : public virtual Private_Key
    {
    public:
+      /*
+      * @return public component of this key
+      */
       virtual MemoryVector<byte> public_value() const = 0;
 
       virtual ~PK_Key_Agreement_Key() {}
diff --git a/src/pubkey/pk_ops.h b/src/pubkey/pk_ops.h
index 97ba372c2..b15a8d8cd 100644
--- a/src/pubkey/pk_ops.h
+++ b/src/pubkey/pk_ops.h
@@ -15,6 +15,9 @@ namespace Botan {
 
 namespace PK_Ops {
 
+/**
+* Public key encryption interface
+*/
 class BOTAN_DLL Encryption
    {
    public:
@@ -26,6 +29,9 @@ class BOTAN_DLL Encryption
       virtual ~Encryption() {}
    };
 
+/**
+* Public key decryption interface
+*/
 class BOTAN_DLL Decryption
    {
    public:
@@ -37,24 +43,27 @@ class BOTAN_DLL Decryption
       virtual ~Decryption() {}
    };
 
+/**
+* Public key signature creation interface
+*/
 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;
 
@@ -70,24 +79,27 @@ class BOTAN_DLL Signature
       virtual ~Signature() {}
    };
 
+/**
+* Public key signature verification interface
+*/
 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; }
 
@@ -127,8 +139,8 @@ class BOTAN_DLL Verification
       virtual ~Verification() {}
    };
 
-/*
-* A generic Key Agreement Operation (eg DH or ECDH)
+/**
+* A generic key agreement Operation (eg DH or ECDH)
 */
 class BOTAN_DLL Key_Agreement
    {
diff --git a/src/pubkey/pkcs8.cpp b/src/pubkey/pkcs8.cpp
index 7353be42f..7d9c0d834 100644
--- a/src/pubkey/pkcs8.cpp
+++ b/src/pubkey/pkcs8.cpp
@@ -129,43 +129,39 @@ SecureVector<byte> PKCS8_decode(DataSource& source, const User_Interface& ui,
 }
 
 /*
-* DER or PEM encode a PKCS #8 private key
+* BER encode a PKCS #8 private key, unencrypted
 */
-void encode(const Private_Key& key, Pipe& pipe, X509_Encoding encoding)
+SecureVector<byte> BER_encode(const Private_Key& key)
    {
    const u32bit PKCS8_VERSION = 0;
 
-   SecureVector<byte> contents =
-      DER_Encoder()
+   return DER_Encoder()
          .start_cons(SEQUENCE)
             .encode(PKCS8_VERSION)
             .encode(key.pkcs8_algorithm_identifier())
             .encode(key.pkcs8_private_key(), OCTET_STRING)
          .end_cons()
       .get_contents();
+   }
 
-   if(encoding == PEM)
-      pipe.write(PEM_Code::encode(contents, "PRIVATE KEY"));
-   else
-      pipe.write(contents);
+/*
+* PEM encode a PKCS #8 private key, unencrypted
+*/
+std::string PEM_encode(const Private_Key& key)
+   {
+   return PEM_Code::encode(PKCS8::BER_encode(key), "PRIVATE KEY");
    }
 
 /*
-* Encode and encrypt a PKCS #8 private key
+* BER encode a PKCS #8 private key, encrypted
 */
-void encrypt_key(const Private_Key& key,
-                 Pipe& pipe,
-                 RandomNumberGenerator& rng,
-                 const std::string& pass, const std::string& pbe_algo,
-                 X509_Encoding encoding)
+SecureVector<byte> BER_encode(const Private_Key& key,
+                              RandomNumberGenerator& rng,
+                              const std::string& pass,
+                              const std::string& pbe_algo)
    {
    const std::string DEFAULT_PBE = "PBE-PKCS5v20(SHA-1,AES-128/CBC)";
 
-   Pipe raw_key;
-   raw_key.start_msg();
-   encode(key, raw_key, RAW_BER);
-   raw_key.end_msg();
-
    std::unique_ptr<PBE> pbe(get_pbe(((pbe_algo != "") ? pbe_algo : DEFAULT_PBE)));
 
    pbe->new_params(rng);
@@ -174,36 +170,18 @@ void encrypt_key(const Private_Key& key,
    AlgorithmIdentifier pbe_algid(pbe->get_oid(), pbe->encode_params());
 
    Pipe key_encrytor(pbe.release());
-   key_encrytor.process_msg(raw_key);
+   key_encrytor.process_msg(PKCS8::BER_encode(key));
 
-   SecureVector<byte> enc_key =
-      DER_Encoder()
+   return DER_Encoder()
          .start_cons(SEQUENCE)
             .encode(pbe_algid)
             .encode(key_encrytor.read_all(), OCTET_STRING)
          .end_cons()
       .get_contents();
-
-   if(encoding == PEM)
-      pipe.write(PEM_Code::encode(enc_key, "ENCRYPTED PRIVATE KEY"));
-   else
-      pipe.write(enc_key);
    }
 
 /*
-* PEM encode a PKCS #8 private key
-*/
-std::string PEM_encode(const Private_Key& key)
-   {
-   Pipe pem;
-   pem.start_msg();
-   encode(key, pem, PEM);
-   pem.end_msg();
-   return pem.read_all_as_string();
-   }
-
-/*
-* Encrypt and PEM encode a PKCS #8 private key
+* PEM encode a PKCS #8 private key, encrypted
 */
 std::string PEM_encode(const Private_Key& key,
                        RandomNumberGenerator& rng,
@@ -213,11 +191,8 @@ std::string PEM_encode(const Private_Key& key,
    if(pass == "")
       return PEM_encode(key);
 
-   Pipe pem;
-   pem.start_msg();
-   encrypt_key(key, pem, rng, pass, pbe_algo, PEM);
-   pem.end_msg();
-   return pem.read_all_as_string();
+   return PEM_Code::encode(PKCS8::BER_encode(key, rng, pass, pbe_algo),
+                           "ENCRYPTED PRIVATE KEY");
    }
 
 /*
@@ -275,13 +250,7 @@ Private_Key* load_key(const std::string& fsname,
 Private_Key* copy_key(const Private_Key& key,
                       RandomNumberGenerator& rng)
    {
-   Pipe bits;
-
-   bits.start_msg();
-   PKCS8::encode(key, bits);
-   bits.end_msg();
-
-   DataSource_Memory source(bits.read_all());
+   DataSource_Memory source(PEM_encode(key));
    return PKCS8::load_key(source, rng);
    }
 
diff --git a/src/pubkey/pkcs8.h b/src/pubkey/pkcs8.h
index 920f8c24a..3da96d840 100644
--- a/src/pubkey/pkcs8.h
+++ b/src/pubkey/pkcs8.h
@@ -25,38 +25,33 @@ struct BOTAN_DLL PKCS8_Exception : public Decoding_Error
 namespace PKCS8 {
 
 /**
-* Encode a private key into a pipe.
+* BER encode a private key
 * @param key the private key to encode
-* @param pipe the pipe to feed the encoded key into
-* @param enc the encoding type to use
+* @return BER encoded key
 */
-BOTAN_DLL void encode(const Private_Key& key, Pipe& pipe,
-                      X509_Encoding enc = PEM);
+BOTAN_DLL SecureVector<byte> BER_encode(const Private_Key& key);
 
 /**
-* Encode and encrypt a private key into a pipe.
-* @param key the private key to encode
-* @param pipe the pipe to feed the encoded key into
-* @param pass the password to use for encryption
-* @param rng the rng to use
-* @param pbe_algo the name of the desired password-based encryption algorithm;
-         if empty ("") a reasonable (portable/secure) default will be chosen.
-* @param enc the encoding type to use
+* Get a string containing a PEM encoded private key.
+* @param key the key to encode
+* @return encoded key
 */
-BOTAN_DLL void encrypt_key(const Private_Key& key,
-                           Pipe& pipe,
-                           RandomNumberGenerator& rng,
-                           const std::string& pass,
-                           const std::string& pbe_algo = "",
-                           X509_Encoding enc = PEM);
-
+BOTAN_DLL std::string PEM_encode(const Private_Key& key);
 
 /**
-* Get a string containing a PEM encoded private key.
+* Encrypt a key using PKCS #8 encryption
 * @param key the key to encode
-* @return the encoded key
+* @param rng the rng to use
+* @param pass the password to use for encryption
+* @param pbe_algo the name of the desired password-based encryption
+         algorithm; if empty ("") a reasonable (portable/secure)
+         default will be chosen.
+* @return encrypted key in binary BER form
 */
-BOTAN_DLL std::string PEM_encode(const Private_Key& key);
+BOTAN_DLL SecureVector<byte> BER_encode(const Private_Key& key,
+                                        RandomNumberGenerator& rng,
+                                        const std::string& pass,
+                                        const std::string& pbe_algo = "");
 
 /**
 * Get a string containing a PEM encoded private key, encrypting it with a
@@ -64,20 +59,67 @@ BOTAN_DLL std::string PEM_encode(const Private_Key& key);
 * @param key the key to encode
 * @param rng the rng to use
 * @param pass the password to use for encryption
-* @param pbe_algo the name of the desired password-based encryption algorithm;
-         if empty ("") a reasonable (portable/secure) default will be chosen.
+* @param pbe_algo the name of the desired password-based encryption
+         algorithm; if empty ("") a reasonable (portable/secure)
+         default will be chosen.
+* @return encrypted key in PEM form
 */
 BOTAN_DLL std::string PEM_encode(const Private_Key& key,
                                  RandomNumberGenerator& rng,
                                  const std::string& pass,
                                  const std::string& pbe_algo = "");
 
+
+/**
+* Encode a private key into a pipe.
+* @deprecated Use PEM_encode or BER_encode instead
+*
+* @param key the private key to encode
+* @param pipe the pipe to feed the encoded key into
+* @param encoding the encoding type to use
+*/
+inline void encode(const Private_Key& key,
+                   Pipe& pipe,
+                   X509_Encoding encoding = PEM)
+   {
+   if(encoding == PEM)
+      pipe.write(PKCS8::PEM_encode(key));
+   else
+      pipe.write(PKCS8::BER_encode(key));
+   }
+
+/**
+* Encode and encrypt a private key into a pipe.
+* @deprecated Use PEM_encode or BER_encode instead
+*
+* @param key the private key to encode
+* @param pipe the pipe to feed the encoded key into
+* @param pass the password to use for encryption
+* @param rng the rng to use
+* @param pbe_algo the name of the desired password-based encryption
+         algorithm; if empty ("") a reasonable (portable/secure)
+         default will be chosen.
+* @param encoding the encoding type to use
+*/
+inline void encrypt_key(const Private_Key& key,
+                        Pipe& pipe,
+                        RandomNumberGenerator& rng,
+                        const std::string& pass,
+                        const std::string& pbe_algo = "",
+                        X509_Encoding encoding = PEM)
+   {
+   if(encoding == PEM)
+      pipe.write(PKCS8::PEM_encode(key, rng, pass, pbe_algo));
+   else
+      pipe.write(PKCS8::BER_encode(key, rng, pass, pbe_algo));
+   }
+
 /**
 * Load a key from a data source.
 * @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,
@@ -88,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,
@@ -99,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,
@@ -110,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,
@@ -120,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 eeb4d5841..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)
@@ -145,7 +145,7 @@ class BOTAN_DLL PK_Signer
 
       /**
       * Add a message part (single byte).
-      * @param the byte to add
+      * @param in the byte to add
       */
       void update(byte in) { update(&in, 1); }
 
@@ -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);
 
@@ -305,8 +305,8 @@ class BOTAN_DLL PK_Verifier
       Signature_Format sig_format;
    };
 
-/*
-* Key Agreement
+/**
+* Key used for key agreement
 */
 class BOTAN_DLL PK_Key_Agreement
    {
@@ -438,6 +438,12 @@ class BOTAN_DLL PK_Decryptor_EME : public PK_Decryptor
       const EME* eme;
    };
 
+/*
+* Typedefs for compatability with 1.8
+*/
+typedef PK_Encryptor_EME PK_Encryptor_MR_with_EME;
+typedef PK_Decryptor_EME PK_Decryptor_MR_with_EME;
+
 }
 
 #endif
diff --git a/src/pubkey/rsa/rsa.h b/src/pubkey/rsa/rsa.h
index e2da173f9..f7700e08c 100644
--- a/src/pubkey/rsa/rsa.h
+++ b/src/pubkey/rsa/rsa.h
@@ -42,7 +42,7 @@ class BOTAN_DLL RSA_PublicKey : public virtual IF_Scheme_PublicKey
    };
 
 /**
-* RSA Private Key class.
+* RSA Private Key
 */
 class BOTAN_DLL RSA_PrivateKey : public RSA_PublicKey,
                                  public IF_Scheme_PrivateKey
@@ -83,6 +83,9 @@ class BOTAN_DLL RSA_PrivateKey : public RSA_PublicKey,
                      u32bit bits, u32bit exp = 65537);
    };
 
+/**
+* RSA private (decrypt/sign) operation
+*/
 class BOTAN_DLL RSA_Private_Operation : public PK_Ops::Signature,
                                         public PK_Ops::Decryption
    {
@@ -107,6 +110,9 @@ class BOTAN_DLL RSA_Private_Operation : public PK_Ops::Signature,
       Blinder blinder;
    };
 
+/**
+* RSA public (encrypt/verify) operation
+*/
 class BOTAN_DLL RSA_Public_Operation : public PK_Ops::Verification,
                                        public PK_Ops::Encryption
    {
diff --git a/src/pubkey/rw/rw.h b/src/pubkey/rw/rw.h
index 831c7a960..24f4ffab6 100644
--- a/src/pubkey/rw/rw.h
+++ b/src/pubkey/rw/rw.h
@@ -15,7 +15,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Rabin-Williams Public Key
 */
 class BOTAN_DLL RW_PublicKey : public virtual IF_Scheme_PublicKey
@@ -36,7 +36,7 @@ class BOTAN_DLL RW_PublicKey : public virtual IF_Scheme_PublicKey
       RW_PublicKey() {}
    };
 
-/*
+/**
 * Rabin-Williams Private Key
 */
 class BOTAN_DLL RW_PrivateKey : public RW_PublicKey,
@@ -59,6 +59,9 @@ class BOTAN_DLL RW_PrivateKey : public RW_PublicKey,
       bool check_key(RandomNumberGenerator& rng, bool) const;
    };
 
+/**
+* Rabin-Williams Signature Operation
+*/
 class BOTAN_DLL RW_Signature_Operation : public PK_Ops::Signature
    {
    public:
@@ -79,6 +82,9 @@ class BOTAN_DLL RW_Signature_Operation : public PK_Ops::Signature
       Blinder blinder;
    };
 
+/**
+* Rabin-Williams Verification Operation
+*/
 class BOTAN_DLL RW_Verification_Operation : public PK_Ops::Verification
    {
    public:
diff --git a/src/pubkey/x509_key.cpp b/src/pubkey/x509_key.cpp
index babeb517f..d321ce338 100644
--- a/src/pubkey/x509_key.cpp
+++ b/src/pubkey/x509_key.cpp
@@ -1,6 +1,6 @@
 /*
 * X.509 Public Key
-* (C) 1999-2007 Jack Lloyd
+* (C) 1999-2010 Jack Lloyd
 *
 * Distributed under the terms of the Botan license
 */
@@ -18,23 +18,14 @@ namespace Botan {
 
 namespace X509 {
 
-/*
-* DER or PEM encode a X.509 public key
-*/
-void encode(const Public_Key& key, Pipe& pipe, X509_Encoding encoding)
+MemoryVector<byte> BER_encode(const Public_Key& key)
    {
-   MemoryVector<byte> der =
-      DER_Encoder()
+   return DER_Encoder()
          .start_cons(SEQUENCE)
             .encode(key.algorithm_identifier())
             .encode(key.x509_subject_public_key(), BIT_STRING)
          .end_cons()
       .get_contents();
-
-   if(encoding == PEM)
-      pipe.write(PEM_Code::encode(der, "PUBLIC KEY"));
-   else
-      pipe.write(der);
    }
 
 /*
@@ -42,11 +33,8 @@ void encode(const Public_Key& key, Pipe& pipe, X509_Encoding encoding)
 */
 std::string PEM_encode(const Public_Key& key)
    {
-   Pipe pem;
-   pem.start_msg();
-   encode(key, pem, PEM);
-   pem.end_msg();
-   return pem.read_all_as_string();
+   return PEM_Code::encode(X509::BER_encode(key),
+                           "PUBLIC KEY");
    }
 
 /*
@@ -115,11 +103,7 @@ Public_Key* load_key(const MemoryRegion<byte>& mem)
 */
 Public_Key* copy_key(const Public_Key& key)
    {
-   Pipe bits;
-   bits.start_msg();
-   X509::encode(key, bits, RAW_BER);
-   bits.end_msg();
-   DataSource_Memory source(bits.read_all());
+   DataSource_Memory source(PEM_encode(key));
    return X509::load_key(source);
    }
 
diff --git a/src/pubkey/x509_key.h b/src/pubkey/x509_key.h
index 13f11646e..4b17f9974 100644
--- a/src/pubkey/x509_key.h
+++ b/src/pubkey/x509_key.h
@@ -1,6 +1,6 @@
 /*
 * X.509 Public Key
-* (C) 1999-2007 Jack Lloyd
+* (C) 1999-2010 Jack Lloyd
 *
 * Distributed under the terms of the Botan license
 */
@@ -16,51 +16,49 @@
 namespace Botan {
 
 /**
-* This namespace contains functions for handling X509 objects.
+* This namespace contains functions for handling X.509 public keys
 */
 namespace X509 {
 
 /**
-* Encode a key into a pipe.
+* BER encode a key
 * @param key the public key to encode
-* @param pipe the pipe to feed the encoded key into
-* @param enc the encoding type to use
+* @return BER encoding of this key
 */
-BOTAN_DLL void encode(const Public_Key& key, Pipe& pipe,
-                      X509_Encoding enc = PEM);
+BOTAN_DLL MemoryVector<byte> BER_encode(const Public_Key& key);
 
 /**
 * PEM encode a public key into a string.
 * @param key the key to encode
-* @return the PEM encoded key
+* @return PEM encoded key
 */
 BOTAN_DLL std::string PEM_encode(const Public_Key& key);
 
 /**
 * Create a public key from a data source.
 * @param source the source providing the DER or PEM encoded key
-* @return the new public key object
+* @return new public key object
 */
 BOTAN_DLL Public_Key* load_key(DataSource& source);
 
 /**
-* Create a public key from a string.
-* @param enc the string containing the PEM encoded key
-* @return the new public key object
+* Create a public key from a file
+* @param filename pathname to the file to load
+* @return new public key object
 */
-BOTAN_DLL Public_Key* load_key(const std::string& enc);
+BOTAN_DLL Public_Key* load_key(const std::string& filename);
 
 /**
 * Create a public key from a memory region.
 * @param enc the memory region containing the DER or PEM encoded key
-* @return the new public key object
+* @return new public key object
 */
 BOTAN_DLL Public_Key* load_key(const MemoryRegion<byte>& enc);
 
 /**
 * Copy a key.
 * @param key the public key to copy
-* @return the new public key object
+* @return new public key object
 */
 BOTAN_DLL Public_Key* copy_key(const Public_Key& key);
 
@@ -70,13 +68,30 @@ BOTAN_DLL Public_Key* copy_key(const Public_Key& key);
 * constraints to be placed in the return value is derived
 * @param limits additional limits that will be incorporated into the
 * return value
-* @return the combination of key type specific constraints and
+* @return combination of key type specific constraints and
 * additional limits
 */
-
 BOTAN_DLL Key_Constraints find_constraints(const Public_Key& pub_key,
                                            Key_Constraints limits);
 
+/**
+* Encode a key into a pipe.
+* @deprecated Use PEM_encode or BER_encode instead
+*
+* @param key the public key to encode
+* @param pipe the pipe to feed the encoded key into
+* @param encoding the encoding type to use
+*/
+inline void encode(const Public_Key& key,
+                      Pipe& pipe,
+                      X509_Encoding encoding = PEM)
+   {
+   if(encoding == PEM)
+      pipe.write(X509::PEM_encode(key));
+   else
+      pipe.write(X509::BER_encode(key));
+   }
+
 }
 
 }
diff --git a/src/rng/auto_rng/auto_rng.h b/src/rng/auto_rng/auto_rng.h
index 90f342a50..28a603feb 100644
--- a/src/rng/auto_rng/auto_rng.h
+++ b/src/rng/auto_rng/auto_rng.h
@@ -14,6 +14,9 @@
 
 namespace Botan {
 
+/**
+* An automatically seeded PRNG
+*/
 class BOTAN_DLL AutoSeeded_RNG : public RandomNumberGenerator
    {
    public:
diff --git a/src/rng/hmac_rng/hmac_rng.cpp b/src/rng/hmac_rng/hmac_rng.cpp
index c185a5643..d8c031f6b 100644
--- a/src/rng/hmac_rng/hmac_rng.cpp
+++ b/src/rng/hmac_rng/hmac_rng.cpp
@@ -30,7 +30,7 @@ void hmac_prf(MessageAuthenticationCode* prf,
 
 }
 
-/**
+/*
 * Generate a buffer of random bytes
 */
 void HMAC_RNG::randomize(byte out[], u32bit length)
@@ -53,7 +53,7 @@ void HMAC_RNG::randomize(byte out[], u32bit length)
       }
    }
 
-/**
+/*
 * Poll for entropy and reset the internal keys
 */
 void HMAC_RNG::reseed(u32bit poll_bits)
@@ -114,7 +114,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)
@@ -131,7 +131,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)
@@ -139,7 +139,7 @@ void HMAC_RNG::add_entropy_source(EntropySource* src)
    entropy_sources.push_back(src);
    }
 
-/**
+/*
 * Clear memory of sensitive data
 */
 void HMAC_RNG::clear()
@@ -152,7 +152,7 @@ void HMAC_RNG::clear()
    seeded = false;
    }
 
-/**
+/*
 * Return the name of this type
 */
 std::string HMAC_RNG::name() const
@@ -160,7 +160,7 @@ std::string HMAC_RNG::name() const
    return "HMAC_RNG(" + extractor->name() + "," + prf->name() + ")";
    }
 
-/**
+/*
 * HMAC_RNG Constructor
 */
 HMAC_RNG::HMAC_RNG(MessageAuthenticationCode* extractor_mac,
@@ -208,7 +208,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 c58378b32..d75885a76 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/rng.h b/src/rng/rng.h
index c53d8e22d..687f98d13 100644
--- a/src/rng/rng.h
+++ b/src/rng/rng.h
@@ -82,8 +82,8 @@ class BOTAN_DLL RandomNumberGenerator
          { return (*this); }
    };
 
-/*
-* Null Random Number Generator
+/**
+* Null/stub RNG - fails if you try to use it for anything
 */
 class BOTAN_DLL Null_RNG : public RandomNumberGenerator
    {
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/pbkdf1/pbkdf1.h b/src/s2k/pbkdf1/pbkdf1.h
index 053a2dbe1..c0508d127 100644
--- a/src/s2k/pbkdf1/pbkdf1.h
+++ b/src/s2k/pbkdf1/pbkdf1.h
@@ -29,10 +29,14 @@ class BOTAN_DLL PKCS5_PBKDF1 : public S2K
 
       /**
       * Create a PKCS #5 instance using the specified hash function.
-      * @param hash a pointer to a hash function object to use
+      * @param hash_in pointer to a hash function object to use
       */
       PKCS5_PBKDF1(HashFunction* hash_in) : hash(hash_in) {}
 
+      /**
+      * Copy constructor
+      * @param other the object to copy
+      */
       PKCS5_PBKDF1(const PKCS5_PBKDF1& other) :
          S2K(), hash(other.hash->clone()) {}
 
diff --git a/src/s2k/pgps2k/pgp_s2k.h b/src/s2k/pgps2k/pgp_s2k.h
index 7f25623f3..cfe9bf5d5 100644
--- a/src/s2k/pgps2k/pgp_s2k.h
+++ b/src/s2k/pgps2k/pgp_s2k.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* OpenPGP S2K
+/**
+* OpenPGP's S2K
 */
 class BOTAN_DLL OpenPGP_S2K : public S2K
    {
@@ -27,6 +27,9 @@ class BOTAN_DLL OpenPGP_S2K : public S2K
                              const byte salt[], u32bit salt_len,
                              u32bit iterations) const;
 
+      /**
+      * @param hash_in the hash function to use
+      */
       OpenPGP_S2K(HashFunction* hash_in) : hash(hash_in) {}
       ~OpenPGP_S2K() { delete hash; }
    private:
diff --git a/src/s2k/s2k.h b/src/s2k/s2k.h
index db59a5fe8..d6880db5d 100644
--- a/src/s2k/s2k.h
+++ b/src/s2k/s2k.h
@@ -12,21 +12,22 @@
 
 namespace Botan {
 
-/*
-* S2K Interface
+/**
+* Base class for S2K (string to key) operations, which convert a
+* password/passphrase into a key
 */
 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/selftest/selftest.cpp b/src/selftest/selftest.cpp
index a11accbd3..783fa3b00 100644
--- a/src/selftest/selftest.cpp
+++ b/src/selftest/selftest.cpp
@@ -49,8 +49,9 @@ algorithm_kat(const SCAN_Name& algo_name,
 
    const std::string input = search_map(vars, std::string("input"));
    const std::string output = search_map(vars, std::string("output"));
-   const std::string key = search_map(vars, std::string("key"));
-   const std::string iv = search_map(vars, std::string("iv"));
+
+   SymmetricKey key(search_map(vars, std::string("key")));
+   InitializationVector iv(search_map(vars, std::string("iv")));
 
    for(u32bit i = 0; i != providers.size(); ++i)
       {
@@ -96,10 +97,18 @@ algorithm_kat(const SCAN_Name& algo_name,
             }
 
          enc->set_key(key);
-         enc->set_iv(iv);
+
+         if(enc->valid_iv_length(iv.length()))
+            enc->set_iv(iv);
+         else if(!enc->valid_iv_length(0))
+            throw Invalid_IV_Length(algo, iv.length());
 
          dec->set_key(key);
-         dec->set_iv(iv);
+
+         if(dec->valid_iv_length(iv.length()))
+            dec->set_iv(iv);
+         else if(!dec->valid_iv_length(0))
+            throw Invalid_IV_Length(algo, iv.length());
 
          bool enc_ok = test_filter_kat(enc, input, output);
          bool dec_ok = test_filter_kat(dec, output, input);
diff --git a/src/ssl/c_kex.cpp b/src/ssl/c_kex.cpp
index db2198627..5194c8c3d 100644
--- a/src/ssl/c_kex.cpp
+++ b/src/ssl/c_kex.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Client Key Exchange Message
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/cert_req.cpp b/src/ssl/cert_req.cpp
index 4431a4a39..04d7867c6 100644
--- a/src/ssl/cert_req.cpp
+++ b/src/ssl/cert_req.cpp
@@ -1,5 +1,5 @@
-/**
-* Certificate Request Message 
+/*
+* Certificate Request Message
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/cert_ver.cpp b/src/ssl/cert_ver.cpp
index 3edf4266d..dfcf6c7c3 100644
--- a/src/ssl/cert_ver.cpp
+++ b/src/ssl/cert_ver.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Certificate Verify Message
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/finished.cpp b/src/ssl/finished.cpp
index b0f6abd25..6648a2c3e 100644
--- a/src/ssl/finished.cpp
+++ b/src/ssl/finished.cpp
@@ -1,5 +1,5 @@
-/**
-* Finished Message 
+/*
+* Finished Message
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/handshake_hash.cpp b/src/ssl/handshake_hash.cpp
index d94fa0178..2331d015e 100644
--- a/src/ssl/handshake_hash.cpp
+++ b/src/ssl/handshake_hash.cpp
@@ -1,5 +1,5 @@
-/**
-* TLS Handshake Hash 
+/*
+* TLS Handshake Hash
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/handshake_hash.h b/src/ssl/handshake_hash.h
index cfb351765..8e068f3de 100644
--- a/src/ssl/handshake_hash.h
+++ b/src/ssl/handshake_hash.h
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Handshake Hash
 * (C) 2004-2006 Jack Lloyd
 *
diff --git a/src/ssl/handshake_state.cpp b/src/ssl/handshake_state.cpp
index 314625057..373d4b57c 100644
--- a/src/ssl/handshake_state.cpp
+++ b/src/ssl/handshake_state.cpp
@@ -1,5 +1,5 @@
-/**
-* TLS Handshaking 
+/*
+* TLS Handshaking
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/hello.cpp b/src/ssl/hello.cpp
index 5b3c32278..2fb5bb567 100644
--- a/src/ssl/hello.cpp
+++ b/src/ssl/hello.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Hello Messages
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/rec_read.cpp b/src/ssl/rec_read.cpp
index f07744c2a..3c008641d 100644
--- a/src/ssl/rec_read.cpp
+++ b/src/ssl/rec_read.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Record Reading
 * (C) 2004-2010 Jack Lloyd
 *
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/**
+/*
 * Reset the state
 */
 void Record_Reader::reset()
@@ -26,7 +26,7 @@ void Record_Reader::reset()
    seq_no = 0;
    }
 
-/**
+/*
 * Set the version to use
 */
 void Record_Reader::set_version(Version_Code version)
@@ -38,7 +38,7 @@ void Record_Reader::set_version(Version_Code version)
    minor = (version & 0xFF);
    }
 
-/**
+/*
 * Set the keys for reading
 */
 void Record_Reader::set_keys(const CipherSuite& suite, const SessionKeys& keys,
@@ -74,7 +74,7 @@ void Record_Reader::set_keys(const CipherSuite& suite, const SessionKeys& keys,
          );
       block_size = block_size_of(cipher_algo);
 
-      if(major == 3 && minor >= 2)
+      if(major > 3 || (major == 3 && minor >= 2))
          iv_size = block_size;
       else
          iv_size = 0;
@@ -106,7 +106,7 @@ void Record_Reader::add_input(const byte input[], u32bit input_size)
    input_queue.write(input, input_size);
    }
 
-/**
+/*
 * Retrieve the next record
 */
 u32bit Record_Reader::get_record(byte& msg_type,
diff --git a/src/ssl/rec_wri.cpp b/src/ssl/rec_wri.cpp
index f8079c235..2ee0e20d3 100644
--- a/src/ssl/rec_wri.cpp
+++ b/src/ssl/rec_wri.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Record Writing
 * (C) 2004-2010 Jack Lloyd
 *
@@ -89,7 +89,7 @@ void Record_Writer::set_keys(const CipherSuite& suite, const SessionKeys& keys,
          );
       block_size = block_size_of(cipher_algo);
 
-      if(major == 3 && minor >= 2)
+      if(major > 3 || (major == 3 && minor >= 2))
          iv_size = block_size;
       else
          iv_size = 0;
diff --git a/src/ssl/s_kex.cpp b/src/ssl/s_kex.cpp
index 9b8a3171d..4617d9fb4 100644
--- a/src/ssl/s_kex.cpp
+++ b/src/ssl/s_kex.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Server Key Exchange Message
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/socket.h b/src/ssl/socket.h
index 62ceed028..6d88bd48a 100644
--- a/src/ssl/socket.h
+++ b/src/ssl/socket.h
@@ -1,5 +1,5 @@
-/**
-* Socket Interface 
+/*
+* Socket Interface
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/tls_alerts.h b/src/ssl/tls_alerts.h
index 894bca4af..f189cf507 100644
--- a/src/ssl/tls_alerts.h
+++ b/src/ssl/tls_alerts.h
@@ -1,5 +1,5 @@
-/**
-* Alert Message 
+/*
+* Alert Message
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
@@ -18,11 +18,19 @@ namespace Botan {
 class BOTAN_DLL Alert
    {
    public:
+      /**
+      * @return if this alert is a fatal one or not
+      */
       bool is_fatal() const { return fatal; }
+
+      /**
+      * @return type of alert
+      */
       Alert_Type type() const { return type_code; }
 
       /**
       * Deserialize an Alert message
+      * @param buf the serialized alert
       */
       Alert(const MemoryRegion<byte>& buf)
          {
diff --git a/src/ssl/tls_client.cpp b/src/ssl/tls_client.cpp
index 8a4275d93..3b63b2119 100644
--- a/src/ssl/tls_client.cpp
+++ b/src/ssl/tls_client.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Client
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/tls_client.h b/src/ssl/tls_client.h
index 2439a58f0..c9ed3ca37 100644
--- a/src/ssl/tls_client.h
+++ b/src/ssl/tls_client.h
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Client
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/tls_connection.h b/src/ssl/tls_connection.h
index ff55cceab..a6de659c4 100644
--- a/src/ssl/tls_connection.h
+++ b/src/ssl/tls_connection.h
@@ -1,5 +1,5 @@
-/**
-* TLS Connection 
+/*
+* TLS Connection
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/tls_exceptn.h b/src/ssl/tls_exceptn.h
index 3ba852875..a9efc718a 100644
--- a/src/ssl/tls_exceptn.h
+++ b/src/ssl/tls_exceptn.h
@@ -1,5 +1,5 @@
-/**
-* Exceptions 
+/*
+* Exceptions
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/tls_magic.h b/src/ssl/tls_magic.h
index 93b56d96d..2a0c61e18 100644
--- a/src/ssl/tls_magic.h
+++ b/src/ssl/tls_magic.h
@@ -1,4 +1,4 @@
-/**
+/*
 * SSL/TLS Protocol Constants
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/tls_messages.h b/src/ssl/tls_messages.h
index 5c0c06c88..20aa9b930 100644
--- a/src/ssl/tls_messages.h
+++ b/src/ssl/tls_messages.h
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Messages
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/tls_policy.cpp b/src/ssl/tls_policy.cpp
index 57fcdb5cc..03a83319c 100644
--- a/src/ssl/tls_policy.cpp
+++ b/src/ssl/tls_policy.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Policies for TLS
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/tls_policy.h b/src/ssl/tls_policy.h
index 75d6d7663..5555f0ca6 100644
--- a/src/ssl/tls_policy.h
+++ b/src/ssl/tls_policy.h
@@ -1,5 +1,5 @@
-/**
-* Policies 
+/*
+* Policies
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/tls_reader.h b/src/ssl/tls_reader.h
index ff3e63ae8..641d1ecdb 100644
--- a/src/ssl/tls_reader.h
+++ b/src/ssl/tls_reader.h
@@ -13,6 +13,9 @@
 
 namespace Botan {
 
+/**
+* Helper class for decoding TLS protocol messages
+*/
 class TLS_Data_Reader
    {
    public:
diff --git a/src/ssl/tls_record.h b/src/ssl/tls_record.h
index 2058933d0..863e2c801 100644
--- a/src/ssl/tls_record.h
+++ b/src/ssl/tls_record.h
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Record Handling
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/tls_server.cpp b/src/ssl/tls_server.cpp
index a4cfcf7de..2a84fa063 100644
--- a/src/ssl/tls_server.cpp
+++ b/src/ssl/tls_server.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Server
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/tls_server.h b/src/ssl/tls_server.h
index 5cf830a64..673f16580 100644
--- a/src/ssl/tls_server.h
+++ b/src/ssl/tls_server.h
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Server
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/tls_session_key.cpp b/src/ssl/tls_session_key.cpp
index 13575adac..594b99e19 100644
--- a/src/ssl/tls_session_key.cpp
+++ b/src/ssl/tls_session_key.cpp
@@ -1,5 +1,5 @@
-/**
-* TLS Session Key 
+/*
+* TLS Session Key
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/tls_session_key.h b/src/ssl/tls_session_key.h
index b0eba2eb1..98c1b92ff 100644
--- a/src/ssl/tls_session_key.h
+++ b/src/ssl/tls_session_key.h
@@ -1,5 +1,5 @@
-/**
-* TLS Session Key 
+/*
+* TLS Session Key
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/tls_state.h b/src/ssl/tls_state.h
index ddf03a822..1472271e3 100644
--- a/src/ssl/tls_state.h
+++ b/src/ssl/tls_state.h
@@ -1,5 +1,5 @@
-/**
-* TLS Handshaking 
+/*
+* TLS Handshaking
 * (C) 2004-2006 Jack Lloyd
 *
 * Released under the terms of the Botan license
diff --git a/src/ssl/tls_suites.cpp b/src/ssl/tls_suites.cpp
index 5e52e7de2..56e8fee01 100644
--- a/src/ssl/tls_suites.cpp
+++ b/src/ssl/tls_suites.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * TLS Cipher Suites
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/tls_suites.h b/src/ssl/tls_suites.h
index fa015c28f..612c148e6 100644
--- a/src/ssl/tls_suites.h
+++ b/src/ssl/tls_suites.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Cipher Suites
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/ssl/unix_socket/info.txt b/src/ssl/unix_socket/info.txt
index 205d0c700..15fc50f5b 100644
--- a/src/ssl/unix_socket/info.txt
+++ b/src/ssl/unix_socket/info.txt
@@ -16,6 +16,5 @@ ssl
 linux
 freebsd
 netbsd
-openbsd
 solaris
 </os>
diff --git a/src/ssl/unix_socket/unx_sock.cpp b/src/ssl/unix_socket/unx_sock.cpp
index 9954cdc06..a7c19b70c 100644
--- a/src/ssl/unix_socket/unx_sock.cpp
+++ b/src/ssl/unix_socket/unx_sock.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Unix Socket
 * (C) 2004-2010 Jack Lloyd
 *
diff --git a/src/stream/arc4/arc4.h b/src/stream/arc4/arc4.h
index 07633f9ef..0488783ef 100644
--- a/src/stream/arc4/arc4.h
+++ b/src/stream/arc4/arc4.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* ARC4
+/**
+* Alleged RC4
 */
 class BOTAN_DLL ARC4 : public StreamCipher
    {
@@ -26,7 +26,11 @@ class BOTAN_DLL ARC4 : public StreamCipher
 
       StreamCipher* clone() const { return new ARC4(SKIP); }
 
-      ARC4(u32bit = 0);
+      /**
+      * @param skip skip this many initial bytes in the keystream
+      */
+      ARC4(u32bit skip = 0);
+
       ~ARC4() { clear(); }
    private:
       void key_schedule(const byte[], u32bit);
diff --git a/src/stream/ctr/ctr.cpp b/src/stream/ctr/ctr.cpp
index 421c9f0c0..8a24cd4d0 100644
--- a/src/stream/ctr/ctr.cpp
+++ b/src/stream/ctr/ctr.cpp
@@ -22,7 +22,7 @@ CTR_BE::CTR_BE(BlockCipher* ciph) :
    {
    position = 0;
 
-   counter.resize(permutation->BLOCK_SIZE * permutation->parallelism());
+   counter.resize(permutation->parallel_bytes());
    buffer.resize(counter.size());
    }
 
diff --git a/src/stream/ctr/ctr.h b/src/stream/ctr/ctr.h
index 5f94170cc..fc7ba522f 100644
--- a/src/stream/ctr/ctr.h
+++ b/src/stream/ctr/ctr.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* CTR-BE (Counter, big-endian)
+/**
+* CTR-BE (Counter mode, big-endian)
 */
 class BOTAN_DLL CTR_BE : public StreamCipher
    {
@@ -33,7 +33,10 @@ class BOTAN_DLL CTR_BE : public StreamCipher
 
       void clear();
 
-      CTR_BE(BlockCipher*);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      CTR_BE(BlockCipher* cipher);
       ~CTR_BE();
    private:
       void key_schedule(const byte key[], u32bit key_len);
diff --git a/src/stream/ofb/ofb.h b/src/stream/ofb/ofb.h
index 1985ae5a9..2871dd8ee 100644
--- a/src/stream/ofb/ofb.h
+++ b/src/stream/ofb/ofb.h
@@ -13,8 +13,8 @@
 
 namespace Botan {
 
-/*
-* OFB Mode
+/**
+* Output Feedback Mode
 */
 class BOTAN_DLL OFB : public StreamCipher
    {
@@ -33,7 +33,10 @@ class BOTAN_DLL OFB : public StreamCipher
 
       void clear();
 
-      OFB(BlockCipher*);
+      /**
+      * @param cipher the underlying block cipher to use
+      */
+      OFB(BlockCipher* cipher);
       ~OFB();
    private:
       void key_schedule(const byte key[], u32bit key_len);
diff --git a/src/stream/salsa20/salsa20.h b/src/stream/salsa20/salsa20.h
index 67fe54dda..4ba483082 100644
--- a/src/stream/salsa20/salsa20.h
+++ b/src/stream/salsa20/salsa20.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Salsa20 (and XSalsa20)
+/**
+* DJB's Salsa20 (and XSalsa20)
 */
 class BOTAN_DLL Salsa20 : public StreamCipher
    {
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 cb6fb3481..edeb1aff5 100644
--- a/src/stream/stream_cipher.h
+++ b/src/stream/stream_cipher.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Stream Cipher
 * (C) 1999-2007 Jack Lloyd
 *
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Stream Cipher
+/**
+* Base class for all stream ciphers
 */
 class BOTAN_DLL StreamCipher : public SymmetricAlgorithm
    {
@@ -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[], 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/stream/turing/turing.h b/src/stream/turing/turing.h
index 19d151fca..92c5083a4 100644
--- a/src/stream/turing/turing.h
+++ b/src/stream/turing/turing.h
@@ -12,14 +12,14 @@
 
 namespace Botan {
 
-/*
+/**
 * Turing
 */
 class BOTAN_DLL Turing : public StreamCipher
    {
    public:
       void cipher(const byte in[], byte out[], u32bit length);
-      void set_iv(const byte[], u32bit);
+      void set_iv(const byte iv[], u32bit iv_length);
 
       bool valid_iv_length(u32bit iv_len) const
          { return (iv_len % 4 == 0 && iv_len <= 16); }
diff --git a/src/stream/wid_wake/wid_wake.h b/src/stream/wid_wake/wid_wake.h
index 1c52e8ba1..365a6d9ff 100644
--- a/src/stream/wid_wake/wid_wake.h
+++ b/src/stream/wid_wake/wid_wake.h
@@ -12,8 +12,11 @@
 
 namespace Botan {
 
-/*
+/**
 * WiderWake4+1-BE
+*
+* Note: quite old and possibly not safe; use XSalsa20 or a block
+* cipher in counter mode.
 */
 class BOTAN_DLL WiderWake_41_BE : public StreamCipher
    {
diff --git a/src/sym_algo/sym_algo.h b/src/sym_algo/sym_algo.h
index 929f2a6f0..60180de90 100644
--- a/src/sym_algo/sym_algo.h
+++ b/src/sym_algo/sym_algo.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Symmetric Algorithm Base Class
 * (C) 1999-2007 Jack Lloyd
 *
@@ -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;
 
@@ -52,7 +52,7 @@ class BOTAN_DLL SymmetricAlgorithm
       /**
       * Set the symmetric key of this object.
       * @param key the to be set as a byte array.
-      * @param the length of the byte array.
+      * @param length in bytes of key param
       */
       void set_key(const byte key[], u32bit length)
          {
@@ -87,7 +87,12 @@ class BOTAN_DLL SymmetricAlgorithm
 
       virtual ~SymmetricAlgorithm() {}
    private:
-      virtual void key_schedule(const byte[], u32bit) = 0;
+      /**
+      * Run the key schedule
+      * @param key the key
+      * @param length of key
+      */
+      virtual void key_schedule(const byte key[], u32bit length) = 0;
    };
 
 /**
diff --git a/src/sym_algo/symkey.h b/src/sym_algo/symkey.h
index 5504297a4..450dab306 100644
--- a/src/sym_algo/symkey.h
+++ b/src/sym_algo/symkey.h
@@ -13,43 +13,132 @@
 
 namespace Botan {
 
-/*
+/**
 * Octet String
 */
 class BOTAN_DLL OctetString
    {
    public:
+      /**
+      * @return size of this octet string in bytes
+      */
       u32bit length() const { return bits.size(); }
+
+      /**
+      * @return this object as a SecureVector<byte>
+      */
       SecureVector<byte> bits_of() const { return bits; }
 
+      /**
+      * @return start of this string
+      */
       const byte* begin() const { return bits.begin(); }
+
+      /**
+      * @return end of this string
+      */
       const byte* end() const   { return bits.end(); }
 
+      /**
+      * @return this encoded as hex
+      */
       std::string as_string() const;
 
-      OctetString& operator^=(const OctetString&);
+      /**
+      * XOR the contents of another octet string into this one
+      * @param other octet string
+      * @return reference to this
+      */
+      OctetString& operator^=(const OctetString& other);
 
+      /**
+      * Force to have odd parity
+      */
       void set_odd_parity();
 
-      void change(const std::string&);
-      void change(const byte[], u32bit);
+      /**
+      * Change the contents of this octet string
+      * @param hex_string a hex encoded bytestring
+      */
+      void change(const std::string& hex_string);
+
+      /**
+      * Change the contents of this octet string
+      * @param in the input
+      * @param length of in in bytes
+      */
+      void change(const byte in[], u32bit length);
+
+      /**
+      * Change the contents of this octet string
+      * @param in the input
+      */
       void change(const MemoryRegion<byte>& in) { bits = in; }
 
-      OctetString(class RandomNumberGenerator&, u32bit len);
+      /**
+      * Create a new random OctetString
+      * @param rng is a random number generator
+      * @param len is the desired length in bytes
+      */
+      OctetString(class RandomNumberGenerator& rng, u32bit len);
+
+      /**
+      * Create a new OctetString
+      * @param str is a hex encoded string
+      */
       OctetString(const std::string& str = "") { change(str); }
+
+      /**
+      * Create a new OctetString
+      * @param in is an array
+      * @param len is the length of in in bytes
+      */
       OctetString(const byte in[], u32bit len) { change(in, len); }
+
+      /**
+      * Create a new OctetString
+      * @param in a bytestring
+      */
       OctetString(const MemoryRegion<byte>& in) { change(in); }
    private:
       SecureVector<byte> bits;
    };
 
-/*
-* Operations on Octet Strings
+/**
+* Compare two strings
+* @param x an octet string
+* @param y an octet string
+* @return if x is equal to y
+*/
+BOTAN_DLL bool operator==(const OctetString& x,
+                          const OctetString& y);
+
+/**
+* Compare two strings
+* @param x an octet string
+* @param y an octet string
+* @return if x is not equal to y
+*/
+BOTAN_DLL bool operator!=(const OctetString& x,
+                          const OctetString& y);
+
+/**
+* Concatenate two strings
+* @param x an octet string
+* @param y an octet string
+* @return x concatenated with y
+*/
+BOTAN_DLL OctetString operator+(const OctetString& x,
+                                const OctetString& y);
+
+/**
+* XOR two strings
+* @param x an octet string
+* @param y an octet string
+* @return x XORed with y
 */
-BOTAN_DLL bool operator==(const OctetString&, const OctetString&);
-BOTAN_DLL bool operator!=(const OctetString&, const OctetString&);
-BOTAN_DLL OctetString operator+(const OctetString&, const OctetString&);
-BOTAN_DLL OctetString operator^(const OctetString&, const OctetString&);
+BOTAN_DLL OctetString operator^(const OctetString& x,
+                                const OctetString& y);
 
 /*
 * Alternate Names
diff --git a/src/utils/buf_comp/buf_comp.h b/src/utils/buf_comp/buf_comp.h
index 3f1e90bad..e807e6abf 100644
--- a/src/utils/buf_comp/buf_comp.h
+++ b/src/utils/buf_comp/buf_comp.h
@@ -1,4 +1,4 @@
-/**
+/*
 * BufferedComputation
 * (C) 1999-2007 Jack Lloyd
 *
@@ -29,7 +29,7 @@ class BOTAN_DLL BufferedComputation
       /**
       * Add new input to process.
       * @param in the input to process as a byte array
-      * @param the length of the byte array
+      * @param length of param in in bytes
       */
       void update(const byte in[], u32bit length) { add_data(in, length); }
 
@@ -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/cpuid.cpp b/src/utils/cpuid.cpp
index 19a2db788..4837e7ac4 100644
--- a/src/utils/cpuid.cpp
+++ b/src/utils/cpuid.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Runtime CPU detection
 * (C) 2009 Jack Lloyd
 *
diff --git a/src/utils/cpuid.h b/src/utils/cpuid.h
index 1de97f129..a41e932fb 100644
--- a/src/utils/cpuid.h
+++ b/src/utils/cpuid.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Runtime CPU detection
 * (C) 2009 Jack Lloyd
 *
@@ -12,6 +12,9 @@
 
 namespace Botan {
 
+/**
+* A class handling runtime CPU feature detection
+*/
 class BOTAN_DLL CPUID
    {
    public:
diff --git a/src/utils/datastor/datastor.h b/src/utils/datastor/datastor.h
index 516d0a16b..26a0d418c 100644
--- a/src/utils/datastor/datastor.h
+++ b/src/utils/datastor/datastor.h
@@ -23,6 +23,9 @@ namespace Botan {
 class BOTAN_DLL Data_Store
    {
    public:
+      /**
+      * A search function
+      */
       bool operator==(const Data_Store&) const;
 
       std::multimap<std::string, std::string> search_for(
diff --git a/src/utils/debug.h b/src/utils/debug.h
index 271e0047b..11de7010e 100644
--- a/src/utils/debug.h
+++ b/src/utils/debug.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Internal-use debugging functions for Botan
 * (C) 2009 Jack Lloyd
 *
diff --git a/src/utils/exceptn.h b/src/utils/exceptn.h
index 2ac88aaf6..6dff970b6 100644
--- a/src/utils/exceptn.h
+++ b/src/utils/exceptn.h
@@ -19,7 +19,7 @@ namespace Botan {
 typedef std::runtime_error Exception;
 typedef std::invalid_argument Invalid_Argument;
 
-/*
+/**
 * Invalid_State Exception
 */
 struct BOTAN_DLL Invalid_State : public Exception
@@ -29,7 +29,7 @@ struct BOTAN_DLL Invalid_State : public Exception
       {}
    };
 
-/*
+/**
 * Lookup_Error Exception
 */
 struct BOTAN_DLL Lookup_Error : public Exception
@@ -39,7 +39,7 @@ struct BOTAN_DLL Lookup_Error : public Exception
       {}
    };
 
-/*
+/**
 * Internal_Error Exception
 */
 struct BOTAN_DLL Internal_Error : public Exception
@@ -49,7 +49,7 @@ struct BOTAN_DLL Internal_Error : public Exception
       {}
    };
 
-/*
+/**
 * Invalid_Key_Length Exception
 */
 struct BOTAN_DLL Invalid_Key_Length : public Invalid_Argument
@@ -60,7 +60,7 @@ struct BOTAN_DLL Invalid_Key_Length : public Invalid_Argument
       {}
    };
 
-/*
+/**
 * Invalid_Block_Size Exception
 */
 struct BOTAN_DLL Invalid_Block_Size : public Invalid_Argument
@@ -72,7 +72,7 @@ struct BOTAN_DLL Invalid_Block_Size : public Invalid_Argument
       {}
    };
 
-/*
+/**
 * Invalid_IV_Length Exception
 */
 struct BOTAN_DLL Invalid_IV_Length : public Invalid_Argument
@@ -83,7 +83,7 @@ struct BOTAN_DLL Invalid_IV_Length : public Invalid_Argument
       {}
    };
 
-/*
+/**
 * PRNG_Unseeded Exception
 */
 struct BOTAN_DLL PRNG_Unseeded : public Invalid_State
@@ -93,7 +93,7 @@ struct BOTAN_DLL PRNG_Unseeded : public Invalid_State
       {}
    };
 
-/*
+/**
 * Policy_Violation Exception
 */
 struct BOTAN_DLL Policy_Violation : public Invalid_State
@@ -103,7 +103,7 @@ struct BOTAN_DLL Policy_Violation : public Invalid_State
       {}
    };
 
-/*
+/**
 * Algorithm_Not_Found Exception
 */
 struct BOTAN_DLL Algorithm_Not_Found : public Lookup_Error
@@ -113,7 +113,7 @@ struct BOTAN_DLL Algorithm_Not_Found : public Lookup_Error
       {}
    };
 
-/*
+/**
 * Invalid_Algorithm_Name Exception
 */
 struct BOTAN_DLL Invalid_Algorithm_Name : public Invalid_Argument
@@ -123,7 +123,7 @@ struct BOTAN_DLL Invalid_Algorithm_Name : public Invalid_Argument
       {}
    };
 
-/*
+/**
 * Encoding_Error Exception
 */
 struct BOTAN_DLL Encoding_Error : public Invalid_Argument
@@ -132,7 +132,7 @@ struct BOTAN_DLL Encoding_Error : public Invalid_Argument
       Invalid_Argument("Encoding error: " + name) {}
    };
 
-/*
+/**
 * Decoding_Error Exception
 */
 struct BOTAN_DLL Decoding_Error : public Invalid_Argument
@@ -141,7 +141,7 @@ struct BOTAN_DLL Decoding_Error : public Invalid_Argument
       Invalid_Argument("Decoding error: " + name) {}
    };
 
-/*
+/**
 * Integrity_Failure Exception
 */
 struct BOTAN_DLL Integrity_Failure : public Exception
@@ -150,7 +150,7 @@ struct BOTAN_DLL Integrity_Failure : public Exception
       Exception("Integrity failure: " + what) {}
    };
 
-/*
+/**
 * Invalid_OID Exception
 */
 struct BOTAN_DLL Invalid_OID : public Decoding_Error
@@ -159,7 +159,7 @@ struct BOTAN_DLL Invalid_OID : public Decoding_Error
       Decoding_Error("Invalid ASN.1 OID: " + oid) {}
    };
 
-/*
+/**
 * Stream_IO_Error Exception
 */
 struct BOTAN_DLL Stream_IO_Error : public Exception
@@ -169,7 +169,7 @@ struct BOTAN_DLL Stream_IO_Error : public Exception
       {}
    };
 
-/*
+/**
 * Self Test Failure Exception
 */
 struct BOTAN_DLL Self_Test_Failure : public Internal_Error
@@ -179,7 +179,7 @@ struct BOTAN_DLL Self_Test_Failure : public Internal_Error
       {}
    };
 
-/*
+/**
 * Memory Allocation Exception
 */
 struct BOTAN_DLL Memory_Exhaustion : public std::bad_alloc
diff --git a/src/utils/prefetch.h b/src/utils/prefetch.h
index ede196692..4928c44a0 100644
--- a/src/utils/prefetch.h
+++ b/src/utils/prefetch.h
@@ -12,10 +12,8 @@
 
 namespace Botan {
 
-namespace PREFETCH {
-
 template<typename T>
-inline void readonly(const T* addr, u32bit length)
+inline void prefetch_readonly(const T* addr, u32bit length)
    {
 #if defined(__GNUG__)
    const u32bit Ts_per_cache_line = CPUID::cache_line_size() / sizeof(T);
@@ -26,7 +24,7 @@ inline void readonly(const T* addr, u32bit length)
    }
 
 template<typename T>
-inline void readwrite(const T* addr, u32bit length)
+inline void prefetch_readwrite(const T* addr, u32bit length)
    {
 #if defined(__GNUG__)
    const u32bit Ts_per_cache_line = CPUID::cache_line_size() / sizeof(T);
@@ -38,6 +36,4 @@ inline void readwrite(const T* addr, u32bit length)
 
 }
 
-}
-
 #endif
diff --git a/src/utils/simd_32/simd_32.h b/src/utils/simd_32/simd_32.h
index 23dce0305..15be7713d 100644
--- a/src/utils/simd_32/simd_32.h
+++ b/src/utils/simd_32/simd_32.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Lightweight wrappers for SIMD operations
 * (C) 2009 Jack Lloyd
 *
diff --git a/src/utils/simd_32/simd_altivec.h b/src/utils/simd_32/simd_altivec.h
index 859a48a5f..44e2a4d2b 100644
--- a/src/utils/simd_32/simd_altivec.h
+++ b/src/utils/simd_32/simd_altivec.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Lightweight wrappers around AltiVec for 32-bit operations
 * (C) 2009 Jack Lloyd
 *
diff --git a/src/utils/simd_32/simd_scalar.h b/src/utils/simd_32/simd_scalar.h
index 5cf1a11c3..56b529025 100644
--- a/src/utils/simd_32/simd_scalar.h
+++ b/src/utils/simd_32/simd_scalar.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Scalar emulation of SIMD 32-bit operations
 * (C) 2009 Jack Lloyd
 *
@@ -13,6 +13,10 @@
 
 namespace Botan {
 
+/**
+* Fake SIMD, using plain scalar operations
+* Often still faster than iterative on superscalar machines
+*/
 class SIMD_Scalar
    {
    public:
diff --git a/src/utils/simd_32/simd_sse.h b/src/utils/simd_32/simd_sse.h
index 0189c2e4d..ad3857fbf 100644
--- a/src/utils/simd_32/simd_sse.h
+++ b/src/utils/simd_32/simd_sse.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Lightweight wrappers for SSE2 intrinsics for 32-bit operations
 * (C) 2009 Jack Lloyd
 *
diff --git a/src/utils/time.cpp b/src/utils/time.cpp
index bc9aa8a2f..4fea41c52 100644
--- a/src/utils/time.cpp
+++ b/src/utils/time.cpp
@@ -1,4 +1,4 @@
-/**
+/*
 * Time Functions
 * (C) 1999-2010 Jack Lloyd
 *
diff --git a/src/utils/time.h b/src/utils/time.h
index 44ec704a4..c7a7e0e1a 100644
--- a/src/utils/time.h
+++ b/src/utils/time.h
@@ -1,4 +1,4 @@
-/**
+/*
 * Time Functions
 * (C) 1999-2009 Jack Lloyd
 *
@@ -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(
    const std::chrono::system_clock::time_point& time_point);
diff --git a/src/utils/ui.h b/src/utils/ui.h
index fe62c60fc..f69bb2c6d 100644
--- a/src/utils/ui.h
+++ b/src/utils/ui.h
@@ -13,8 +13,9 @@
 
 namespace Botan {
 
-/*
+/**
 * User Interface
+* Only really used for callbacks for PKCS #8 decryption
 */
 class BOTAN_DLL User_Interface
    {
diff --git a/src/utils/version.cpp b/src/utils/version.cpp
index ef591b4d7..ce2083bc0 100644
--- a/src/utils/version.cpp
+++ b/src/utils/version.cpp
@@ -26,6 +26,8 @@ std::string version_string()
           std::to_string(version_patch());
    }
 
+u32bit version_datestamp() { return BOTAN_VERSION_DATESTAMP; }
+
 /*
 * Return parts of the version as integers
 */
diff --git a/src/utils/version.h b/src/utils/version.h
index 3cc44e806..13d0ac8bb 100644
--- a/src/utils/version.h
+++ b/src/utils/version.h
@@ -19,25 +19,33 @@ namespace Botan {
 
 /**
 * Get the version string identifying the version of Botan.
-* @return the version string
+* @return version string
 */
 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 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();
 
diff --git a/src/utils/xor_buf.h b/src/utils/xor_buf.h
index 0d7d587c8..34abb48d3 100644
--- a/src/utils/xor_buf.h
+++ b/src/utils/xor_buf.h
@@ -1,4 +1,4 @@
-/**
+/*
 * XOR operations
 * (C) 1999-2008 Jack Lloyd
 *
diff --git a/src/wrap/python/rsa.cpp b/src/wrap/python/rsa.cpp
index 41d9bd4d1..903516f11 100644
--- a/src/wrap/python/rsa.cpp
+++ b/src/wrap/python/rsa.cpp
@@ -36,6 +36,14 @@ class Py_RSA_PrivateKey
          return PKCS8::PEM_encode(*rsa_key);
          }
 
+      std::string to_ber() const
+         {
+         SecureVector<byte> bits = PKCS8::BER_encode(*rsa_key);
+
+         return std;:string(reinterpret_cast<const char*>(&bits[0]),
+                            bits.size());
+         }
+
       std::string get_N() const { return bigint2str(get_bigint_N()); }
       std::string get_E() const { return bigint2str(get_bigint_E()); }
 
@@ -113,6 +121,14 @@ class Py_RSA_PublicKey
          return X509::PEM_encode(*rsa_key);
          }
 
+      std::string to_ber() const
+         {
+         SecureVector<byte> bits = X509::BER_encode(*rsa_key);
+
+         return std;:string(reinterpret_cast<const char*>(&bits[0]),
+                            bits.size());
+         }
+
       std::string encrypt(const std::string& in,
                           const std::string& padding,
                           Python_RandomNumberGenerator& rng);
@@ -171,6 +187,7 @@ void export_rsa()
       ("RSA_PublicKey", python::init<std::string>())
       .def(python::init<const Py_RSA_PrivateKey&>())
       .def("to_string", &Py_RSA_PublicKey::to_string)
+      .def("to_ber", &Py_RSA_PublicKey::to_ber)
       .def("encrypt", &Py_RSA_PublicKey::encrypt)
       .def("verify", &Py_RSA_PublicKey::verify)
       .def("get_N", &Py_RSA_PublicKey::get_N)
@@ -180,6 +197,7 @@ void export_rsa()
       ("RSA_PrivateKey", python::init<std::string, Python_RandomNumberGenerator&, std::string>())
        .def(python::init<u32bit, Python_RandomNumberGenerator&>())
        .def("to_string", &Py_RSA_PrivateKey::to_string)
+       .def("to_ber", &Py_RSA_PrivateKey::to_ber)
        .def("decrypt", &Py_RSA_PrivateKey::decrypt)
        .def("sign", &Py_RSA_PrivateKey::sign)
        .def("get_N", &Py_RSA_PrivateKey::get_N)