More Doxygen comments from InSiTo

6 files changed, 104 insertions, 30 deletions

diff --git a/src/core/oid_lookup/oids.h b/src/core/oid_lookup/oids.h
index b5be0e01f..1bf209c61 100644
--- a/src/core/oid_lookup/oids.h
+++ b/src/core/oid_lookup/oids.h
@@ -12,21 +12,41 @@ namespace Botan {
 
 namespace OIDS {
 
-/*************************************************
-* Register an OID to string mapping              *
-*************************************************/
+/**
+* Register an OID to string mapping.
+* @param oid the oid to register
+* @param name the name to be associated with the oid
+*/
 BOTAN_DLL void add_oid(const OID&, const std::string&);
 
-/*************************************************
-* See if an OID exists in the internal table     *
-*************************************************/
+/**
+* See if an OID exists in the internal table.
+* @param oid the oid to check for
+* @return true if the oid is registered
+*/
 BOTAN_DLL bool have_oid(const std::string&);
 
-/*************************************************
-* Perform OID<->string mappings                  *
-*************************************************/
+/**
+* Resolve an OID
+* @param oid the OID to look up
+* @return the name associated with this OID
+*/
 BOTAN_DLL std::string lookup(const 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
+*/
 BOTAN_DLL OID lookup(const std::string&);
+
+/**
+* Tests whether the specified OID stands for the specified name.
+* @param oid the OID to check
+* @param name the name to check
+* @return true if the specified OID stands for the specified name
+*/
 BOTAN_DLL bool name_of(const OID&, const std::string&);
 
 }
diff --git a/src/filters/data_snk.h b/src/filters/data_snk.h
index 9afe9bc4e..67700a8f5 100644
--- a/src/filters/data_snk.h
+++ b/src/filters/data_snk.h
@@ -11,9 +11,9 @@
 
 namespace Botan {
 
-/*************************************************
-* Generic DataSink Interface                     *
-*************************************************/
+/**
+* This class represents abstract data sink objects.
+*/
 class BOTAN_DLL DataSink : public Filter
    {
    public:
@@ -25,16 +25,31 @@ class BOTAN_DLL DataSink : public Filter
       DataSink(const DataSink&);
    };
 
-/*************************************************
-* Stream-Based DataSink                          *
-*************************************************/
+/**
+* This class represents a data sink which writes its output to a stream.
+*/
 class BOTAN_DLL DataSink_Stream : public DataSink
    {
    public:
       void write(const byte[], u32bit);
 
-      DataSink_Stream(std::ostream&, const std::string& = "");
-      DataSink_Stream(const std::string&, bool = false);
+      /**
+      * Construct a DataSink_Stream from a stream.
+      * @param stream the stream to write to
+      * @param name identifier
+      */
+      DataSink_Stream(std::ostream& stream,
+                      const std::string& name = "");
+
+      /**
+      * Construct a DataSink_Stream from a stream.
+      * @param file 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,
+                      bool use_binary = false);
+
       ~DataSink_Stream();
    private:
       const std::string identifier;
diff --git a/src/filters/pbe.h b/src/filters/pbe.h
index 4761f79d9..805acb342 100644
--- a/src/filters/pbe.h
+++ b/src/filters/pbe.h
@@ -13,18 +13,39 @@
 
 namespace Botan {
 
-/*************************************************
-* Password Based Encryption                      *
-*************************************************/
+/**
+* Password Based Encryption (PBE) Filter.
+*/
 class BOTAN_DLL PBE : public Filter
    {
    public:
+      /**
+      * Set this filter's key.
+      * @param pw the password to be used for the encryption
+      */
       virtual void set_key(const std::string&) = 0;
+
+      /**
+      * Create a new random salt value and set the default iterations value.
+      */
       virtual void new_params(RandomNumberGenerator& rng) = 0;
 
+      /**
+      * DER encode the params (the number of iterations and the salt value)
+      * @return the encoded params
+      */
       virtual MemoryVector<byte> encode_params() const = 0;
+
+      /**
+      * 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;
 
+      /**
+      * Get this PBE's OID.
+      * @return the OID
+      */
       virtual OID get_oid() const = 0;
    };
 
diff --git a/src/kdf/pbkdf1/pbkdf1.h b/src/kdf/pbkdf1/pbkdf1.h
index ee76e5b15..99d0188db 100644
--- a/src/kdf/pbkdf1/pbkdf1.h
+++ b/src/kdf/pbkdf1/pbkdf1.h
@@ -11,16 +11,21 @@
 
 namespace Botan {
 
-/*************************************************
-* PKCS #5 PBKDF1                                 *
-*************************************************/
+/**
+* This class implements the PKCS #5 PBKDF1 functionality.
+*/
 class BOTAN_DLL PKCS5_PBKDF1 : public S2K
    {
    public:
       std::string name() const;
       S2K* clone() const;
 
+      /**
+      * Create a PKCS #5 instance using the specified hash function.
+      * @param hash a pointer to a hash function object to use
+      */
       PKCS5_PBKDF1(HashFunction* hash_in) : hash(hash_in) {}
+
       PKCS5_PBKDF1(const PKCS5_PBKDF1& other) :
          S2K(), hash(other.hash->clone()) {}
 
diff --git a/src/kdf/pbkdf2/pbkdf2.h b/src/kdf/pbkdf2/pbkdf2.h
index c0f0229ff..1b27c5acb 100644
--- a/src/kdf/pbkdf2/pbkdf2.h
+++ b/src/kdf/pbkdf2/pbkdf2.h
@@ -11,16 +11,20 @@
 
 namespace Botan {
 
-/*************************************************
-* PKCS #5 PBKDF2                                 *
-*************************************************/
+/**
+* This class implements the PKCS #5 PBKDF2 functionality.
+*/
 class BOTAN_DLL PKCS5_PBKDF2 : public S2K
    {
    public:
       std::string name() const;
       S2K* clone() const;
 
-      PKCS5_PBKDF2(MessageAuthenticationCode* m);
+      /**
+      * Create a PKCS #5 instance using the specified message auth code
+      * @param mac the MAC to use
+      */
+      PKCS5_PBKDF2(MessageAuthenticationCode* mac);
       ~PKCS5_PBKDF2();
    private:
       OctetString derive(u32bit, const std::string&,
diff --git a/src/pbe/pbe_base/get_pbe.h b/src/pbe/pbe_base/get_pbe.h
index e7b434c1f..830dbb29f 100644
--- a/src/pbe/pbe_base/get_pbe.h
+++ b/src/pbe/pbe_base/get_pbe.h
@@ -11,10 +11,19 @@
 
 namespace Botan {
 
-/*************************************************
-* Get a PBE object                               *
-*************************************************/
+/**
+* Factory function for PBEs.
+* @param pbe_name the name of the PBE algorithm to retrieve
+* @return a PBE with randomly created parameters
+*/
 BOTAN_DLL PBE* get_pbe(const std::string&);
+
+/**
+* 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 the PBE with the specified parameters
+*/
 BOTAN_DLL PBE* get_pbe(const OID&, DataSource&);
 
 }