More Doxygen comments from InSiTo

1 files changed, 57 insertions, 5 deletions

diff --git a/src/core/s2k.h b/src/core/s2k.h
index 031592513..3efcff638 100644
--- a/src/core/s2k.h
+++ b/src/core/s2k.h
@@ -17,18 +17,70 @@ namespace Botan {
 class BOTAN_DLL S2K
    {
    public:
+      /**
+      * Create a copy of this object.
+      * @return an auto_ptr to a copy of this object
+      */
       virtual S2K* clone() const = 0;
+
+      /**
+      * Get the algorithm name.
+      * @return the name of this S2K algorithm
+      */
       virtual std::string name() const = 0;
+
+      /**
+      * Clear this objects internal values.
+      */
       virtual void clear() {}
 
-      OctetString derive_key(u32bit, const std::string&) const;
+      /**
+      * Derive a key from a passphrase with this S2K object. It will use
+      * the salt value and number of iterations configured in this object.
+      * @param key_len the desired length of the key to produce
+      * @param passphrase the password to derive the key from
+      */
+      OctetString derive_key(u32bit key_len,
+                             const std::string& passphrase) const;
+
+      /**
+      * Set the number of iterations for the one-way function during
+      * key generation.
+      * @param n the desired number of iterations
+      */
+      void set_iterations(u32bit n);
 
-      void set_iterations(u32bit);
-      void change_salt(const byte[], u32bit);
-      void change_salt(const MemoryRegion<byte>&);
-      void new_random_salt(RandomNumberGenerator& rng, u32bit);
+      /**
+      * Set a new salt value.
+      * @param new_salt a byte array defining the new salt value
+      * @param len the length of the above byte array
+      */
+      void change_salt(const byte new_salt[], u32bit len);
 
+      /**
+      * Set a new salt value.
+      * @param new_salt the new salt value
+      */
+      void change_salt(const MemoryRegion<byte>& new_salt);
+
+      /**
+      * Create a new random salt value using the rng
+      * @param rng the random number generator to use
+      * @param len the desired length of the new salt value
+      */
+      void new_random_salt(RandomNumberGenerator& rng, u32bit len);
+
+      /**
+      * Get the number of iterations for the key derivation currently
+      * configured in this S2K object.
+      * @return the current number of iterations
+      */
       u32bit iterations() const { return iter; }
+
+      /**
+      * Get the currently configured salt value of this S2K object.
+      * @return the current salt value
+      */
       SecureVector<byte> current_salt() const { return salt; }
 
       S2K() { iter = 0; }