More Doxygen fixes

42 files changed, 116 insertions, 70 deletions

diff --git a/src/algo_factory/algo_cache.h b/src/algo_factory/algo_cache.h
index c9fbf5b26..13df8e752 100644
--- a/src/algo_factory/algo_cache.h
+++ b/src/algo_factory/algo_cache.h
@@ -50,6 +50,10 @@ class Algorithm_Cache
       */
       std::vector<std::string> providers_of(const std::string& algo_name);
 
+      /**
+      * Constructor
+      * @param m a mutex to serialize internal access
+      */
       Algorithm_Cache(Mutex* m) : mutex(m) {}
       ~Algorithm_Cache();
    private:
diff --git a/src/algo_factory/algo_factory.h b/src/algo_factory/algo_factory.h
index e8a4914b5..3284942ad 100644
--- a/src/algo_factory/algo_factory.h
+++ b/src/algo_factory/algo_factory.h
@@ -155,8 +155,9 @@ 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
          {
diff --git a/src/alloc/alloc_mmap/mmap_mem.h b/src/alloc/alloc_mmap/mmap_mem.h
index da3dda31d..be1d06cff 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 9735a547d..69555544e 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/system_alloc/defalloc.h b/src/alloc/system_alloc/defalloc.h
index 0c8804223..27ee3cd8f 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 ea21c475f..6800166e6 100644
--- a/src/asn1/asn1_obj.h
+++ b/src/asn1/asn1_obj.h
@@ -17,7 +17,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Attribute
 */
 class BOTAN_DLL Attribute : public ASN1_Object
@@ -34,7 +34,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
@@ -61,7 +61,7 @@ class BOTAN_DLL X509_Time : public ASN1_Object
       ASN1_Tag tag;
    };
 
-/*
+/**
 * Simple String
 */
 class BOTAN_DLL ASN1_String : public ASN1_Object
@@ -82,7 +82,7 @@ class BOTAN_DLL ASN1_String : public ASN1_Object
       ASN1_Tag tag;
    };
 
-/*
+/**
 * Distinguished Name
 */
 class BOTAN_DLL X509_DN : public ASN1_Object
@@ -112,7 +112,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/ber_dec.h b/src/asn1/ber_dec.h
index 3658aeba4..52e309aec 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 3037ee707..ae10b4bc8 100644
--- a/src/asn1/der_enc.h
+++ b/src/asn1/der_enc.h
@@ -16,7 +16,7 @@ namespace Botan {
 class BigInt;
 class ASN1_Object;
 
-/*
+/**
 * General DER Encoding Object
 */
 class BOTAN_DLL DER_Encoder
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..263a9e8a1 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
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/idea/idea.h b/src/block/idea/idea.h
index 1a9644d4e..be1417a36 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
diff --git a/src/block/idea_sse2/idea_sse2.h b/src/block/idea_sse2/idea_sse2.h
index 585de7264..b00e0f400 100644
--- a/src/block/idea_sse2/idea_sse2.h
+++ b/src/block/idea_sse2/idea_sse2.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * IDEA in SSE2
 */
 class BOTAN_DLL IDEA_SSE2 : public IDEA
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..07556399b 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
    {
diff --git a/src/block/lubyrack/lubyrack.h b/src/block/lubyrack/lubyrack.h
index 7249cf157..29b7ee5a4 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
    {
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/noekeon/noekeon.h b/src/block/noekeon/noekeon.h
index abeecbc64..5b04a135d 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
diff --git a/src/block/noekeon_simd/noekeon_simd.h b/src/block/noekeon_simd/noekeon_simd.h
index aba1e3d65..507f17e21 100644
--- a/src/block/noekeon_simd/noekeon_simd.h
+++ b/src/block/noekeon_simd/noekeon_simd.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Noekeon
+/**
+* Noekeon implementation using SIMD operations
 */
 class BOTAN_DLL Noekeon_SIMD : public Noekeon
    {
diff --git a/src/block/rc2/rc2.h b/src/block/rc2/rc2.h
index dd0295572..d4ecac462 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
diff --git a/src/block/rc5/rc5.h b/src/block/rc5/rc5.h
index 82931c1d2..5135336b1 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
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..3386102e4 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
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..2bbe2f71f 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
    {
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 54bfa1dd7..f0a11fc93 100644
--- a/src/block/serpent_simd/serp_simd.h
+++ b/src/block/serpent_simd/serp_simd.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* Serpent
+/**
+* Serpent implementation using SIMD
 */
 class BOTAN_DLL Serpent_SIMD : public Serpent
    {
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 e114bf63a..87eeb433b 100644
--- a/src/block/xtea_simd/xtea_simd.h
+++ b/src/block/xtea_simd/xtea_simd.h
@@ -12,8 +12,8 @@
 
 namespace Botan {
 
-/*
-* XTEA (SIMD variant)
+/**
+* XTEA implemented using SIMD operations
 */
 class BOTAN_DLL XTEA_SIMD : public XTEA
    {
diff --git a/src/filters/filter.h b/src/filters/filter.h
index b840a69da..4773fe159 100644
--- a/src/filters/filter.h
+++ b/src/filters/filter.h
@@ -47,8 +47,20 @@ class BOTAN_DLL Filter
 
       virtual ~Filter() {}
    protected:
-      void send(const byte[], u32bit);
-      void send(byte input) { send(&input, 1); }
+      /**
+      * @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(&input, 1); }
+
+      /**
+      * @param in some input for the filter
+      */
       void send(const MemoryRegion<byte>& in) { send(in.begin(), in.size()); }
       Filter();
    private:
@@ -76,8 +88,17 @@ class BOTAN_DLL Filter
 
       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;
@@ -94,10 +115,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/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/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: