Add some Doxygen comments for BlockCipherModePaddingMethod

1 files changed, 62 insertions, 23 deletions

diff --git a/src/modes/mode_pad/mode_pad.h b/src/modes/mode_pad/mode_pad.h
index 3dc28fa81..5c31a4f1e 100644
--- a/src/modes/mode_pad/mode_pad.h
+++ b/src/modes/mode_pad/mode_pad.h
@@ -1,7 +1,7 @@
-/*************************************************
-* CBC Padding Methods Header File                *
-* (C) 1999-2007 Jack Lloyd                       *
-*************************************************/
+/**
+* CBC Padding Methods Header File
+* (C) 1999-2008 Jack Lloyd
+*/
 
 #ifndef BOTAN_CBC_PADDING_H__
 #define BOTAN_CBC_PADDING_H__
@@ -11,23 +11,62 @@
 
 namespace Botan {
 
-/*************************************************
-* Block Cipher Mode Padding Method               *
-*************************************************/
+/**
+* Block Cipher Mode Padding Method
+* This class is pretty limited, it cannot deal well with
+* randomized padding methods, or any padding method that
+* wants to add more than one block. For instance, it should
+* be possible to define cipher text stealing mode as simply
+* a padding mode for CBC, which happens to consume the last
+* two block (and requires use of the block cipher).
+*/
 class BOTAN_DLL BlockCipherModePaddingMethod
    {
    public:
-      virtual void pad(byte[], u32bit, u32bit) const = 0;
-      virtual u32bit unpad(const byte[], u32bit) const = 0;
-      virtual u32bit pad_bytes(u32bit, u32bit) const;
-      virtual bool valid_blocksize(u32bit) const = 0;
+      /**
+      * @param block output buffer
+      * @param size of the block
+      * @param current_position in the last block
+      */
+      virtual void pad(byte block[],
+                       u32bit size,
+                       u32bit current_position) const = 0;
+
+      /**
+      * @param block the last block
+      * @param size the of the block
+      */
+      virtual u32bit unpad(const byte block[],
+                           u32bit size) const = 0;
+
+      /**
+      * @param block_size of the cipher
+      * @param position in the current block
+      * @return number of padding bytes that will be appended
+      */
+      virtual u32bit pad_bytes(u32bit block_size,
+                               u32bit position) const;
+
+      /**
+      * @param block_size of the cipher
+      * @return valid block size for this padding mode
+      */
+      virtual bool valid_blocksize(u32bit block_size) const = 0;
+
+      /**
+      * @return name of the mode
+      */
       virtual std::string name() const = 0;
+
+      /**
+      * virtual destructor
+      */
       virtual ~BlockCipherModePaddingMethod() {}
    };
 
-/*************************************************
-* PKCS#7 Padding                                 *
-*************************************************/
+/**
+* PKCS#7 Padding
+*/
 class BOTAN_DLL PKCS7_Padding : public BlockCipherModePaddingMethod
    {
    public:
@@ -37,9 +76,9 @@ class BOTAN_DLL PKCS7_Padding : public BlockCipherModePaddingMethod
       std::string name() const { return "PKCS7"; }
    };
 
-/*************************************************
-* ANSI X9.23 Padding                             *
-*************************************************/
+/**
+* ANSI X9.23 Padding
+*/
 class BOTAN_DLL ANSI_X923_Padding : public BlockCipherModePaddingMethod
    {
    public:
@@ -49,9 +88,9 @@ class BOTAN_DLL ANSI_X923_Padding : public BlockCipherModePaddingMethod
       std::string name() const { return "X9.23"; }
    };
 
-/*************************************************
-* One And Zeros Padding                          *
-*************************************************/
+/**
+* One And Zeros Padding
+*/
 class BOTAN_DLL OneAndZeros_Padding : public BlockCipherModePaddingMethod
    {
    public:
@@ -61,9 +100,9 @@ class BOTAN_DLL OneAndZeros_Padding : public BlockCipherModePaddingMethod
       std::string name() const { return "OneAndZeros"; }
    };
 
-/*************************************************
-* Null Padding                                   *
-*************************************************/
+/**
+* Null Padding
+*/
 class BOTAN_DLL Null_Padding : public BlockCipherModePaddingMethod
    {
    public: