Update documentation

cryptlib.h

@@ -605,11 +605,13 @@ public:
 	/// \brief Returns smallest valid key length
 	/// \returns the minimum key length, in bytes
 	virtual size_t MinKeyLength() const =0;
+
 	/// \brief Returns largest valid key length
 	/// \returns the maximum key length, in bytes
 	virtual size_t MaxKeyLength() const =0;
+
 	/// \brief Returns default key length
-	/// \returns the default (recommended) key length, in bytes
+	/// \returns the default key length, in bytes
 	virtual size_t DefaultKeyLength() const =0;
 
 	/// \brief Returns a valid key length for the algorithm

modes.h

@@ -50,17 +50,53 @@ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CipherModeBase : public SymmetricCipher
 {
 public:
 	virtual ~CipherModeBase() {}
-	size_t MinKeyLength() const {return m_cipher->MinKeyLength();}
-	size_t MaxKeyLength() const {return m_cipher->MaxKeyLength();}
-	size_t DefaultKeyLength() const {return m_cipher->DefaultKeyLength();}
-	size_t GetValidKeyLength(size_t n) const {return m_cipher->GetValidKeyLength(n);}
-	bool IsValidKeyLength(size_t n) const {return m_cipher->IsValidKeyLength(n);}
 
+	/// \brief Returns smallest valid key length
+	/// \returns the minimum key length, in bytes
+	size_t MinKeyLength() const {return m_cipher->MinKeyLength();}
+
+	/// \brief Returns largest valid key length
+	/// \returns the maximum key length, in bytes
+	size_t MaxKeyLength() const {return m_cipher->MaxKeyLength();}
+
+	/// \brief Returns default key length
+	/// \returns the default key length, in bytes
+	size_t DefaultKeyLength() const {return m_cipher->DefaultKeyLength();}
+
+	/// \brief Returns a valid key length for the algorithm
+	/// \param keylength the size of the key, in bytes
+	/// \returns the valid key length, in bytes
+	/// \details keylength is provided in bytes, not bits. If keylength is less than MIN_KEYLENGTH,
+	///   then the function returns MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH,
+	///   then the function returns MAX_KEYLENGTH. if If keylength is a multiple of KEYLENGTH_MULTIPLE,
+	///   then keylength is returned. Otherwise, the function returns a \a lower multiple of
+	///   KEYLENGTH_MULTIPLE.
+	size_t GetValidKeyLength(size_t keylength) const {return m_cipher->GetValidKeyLength(keylength);}
+
+	/// \brief Returns whether keylength is a valid key length
+	/// \param keylength the requested keylength
+	/// \return true if keylength is valid, false otherwise
+	/// \details Internally the function calls GetValidKeyLength()
+	bool IsValidKeyLength(size_t keylength) const {return m_cipher->IsValidKeyLength(keylength);}
+
+	/// \brief Provides input and output data alignment for optimal performance.
+	/// \return the input data alignment that provides optimal performance
+	/// \sa GetAlignment() and OptimalBlockSize()
 	unsigned int OptimalDataAlignment() const {return m_cipher->OptimalDataAlignment();}
 
+	/// \brief Returns length of the IV accepted by this object
+	/// \return the size of an IV, in bytes
+	/// \throws NotImplemented() if the object does not support resynchronization
+	/// \details The default implementation throws NotImplemented
 	unsigned int IVSize() const {return BlockSize();}
+
+	/// \brief Minimal requirement for secure IVs
+	/// \return the secure IV requirement of the algorithm
 	virtual IV_Requirement IVRequirement() const =0;
 
+	/// \brief Set external block cipher
+	/// \param cipher An external block cipher
+	/// \details The cipher should be keyed.
 	void SetCipher(BlockCipher &cipher)
 	{
 		this->ThrowIfResynchronizable();
@@ -68,6 +104,11 @@ public:
 		this->ResizeBuffers();
 	}
 
+	/// \brief Set external block cipher and IV
+	/// \param cipher An external block cipher
+	/// \param iv a byte array used to resynchronize the cipher
+	/// \param feedbackSize the feedback size, in bytes
+	/// \details The cipher should be keyed.
 	void SetCipherWithIV(BlockCipher &cipher, const byte *iv, int feedbackSize = 0)
 	{
 		this->ThrowIfInvalidIV(iv);
@@ -315,12 +356,30 @@ template <class BASE>
 class CipherModeFinalTemplate_ExternalCipher : public BASE
 {
 public:
+	/// \brief Construct a default CipherModeFinalTemplate
+	/// \details The cipher is not keyed.
 	CipherModeFinalTemplate_ExternalCipher() {}
+
+	/// \brief Construct a CipherModeFinalTemplate
+	/// \param cipher An external block cipher
+	/// \details The cipher should be keyed.
 	CipherModeFinalTemplate_ExternalCipher(BlockCipher &cipher)
 		{this->SetCipher(cipher);}
+
+	/// \brief Construct a CipherModeFinalTemplate
+	/// \param cipher An external block cipher
+	/// \param iv a byte array used to resynchronize the cipher
+	/// \param feedbackSize the feedback size, in bytes
+	/// \details The cipher should be keyed.
 	CipherModeFinalTemplate_ExternalCipher(BlockCipher &cipher, const byte *iv, int feedbackSize = 0)
 		{this->SetCipherWithIV(cipher, iv, feedbackSize);}
 
+	/// \brief Provides the name of this algorithm
+	/// \return the standard algorithm name
+	/// \details The standard algorithm name can be a name like \a AES or \a AES/GCM. Some algorithms
+	///   do not have standard names yet. For example, there is no standard algorithm name for
+	///   Shoup's ECIES.
+	/// \note  AlgorithmName is not universally implemented yet
 	std::string AlgorithmName() const
 		{return (this->m_cipher ? this->m_cipher->AlgorithmName() + "/" : std::string("")) + BASE::StaticAlgorithmName();}
 };

seckey.h

@@ -311,8 +311,9 @@ public:
 	SimpleKeyingInterface::IV_Requirement IVRequirement() const
 		{return (SimpleKeyingInterface::IV_Requirement)INFO::IV_REQUIREMENT;}
 
-	/// \brief The default initialization vector length for the algorithm
+	/// \brief The initialization vector length for the algorithm
-	/// \details IVSize is provided in bytes, not bits. The default implementation uses IV_LENGTH, which is 0.
+	/// \details IVSize is provided in bytes, not bits. The default implementation uses
+	///   IV_LENGTH, which is 0.
 	unsigned int IVSize() const
 		{return INFO::IV_LENGTH;}
 };