Updated documentation

Doxyfile

@@ -614,7 +614,7 @@ GENERATE_TESTLIST      = YES
 # list. This list is created by putting \bug commands in the documentation.
 # The default value is: YES.
 
-GENERATE_BUGLIST       = YES
+GENERATE_BUGLIST       = NO
 
 # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)
 # the deprecated list. This list is created by putting \deprecated commands in
@@ -765,7 +765,8 @@ WARN_LOGFILE           =
 
 INPUT                  = . \
                          GNUmakefile \
-						 rdrand.asm
+						 rdrand.asm \
+						 rdrand.S
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -934,13 +935,13 @@ STRIP_CODE_COMMENTS    = NO
 # function all documented functions referencing it will be listed.
 # The default value is: NO.
 
-REFERENCED_BY_RELATION = YES
+REFERENCED_BY_RELATION = NO
 
 # If the REFERENCES_RELATION tag is set to YES then for each documented function
 # all documented entities called/used by that function will be listed.
 # The default value is: NO.
 
-REFERENCES_RELATION    = YES
+REFERENCES_RELATION    = NO
 
 # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set
 # to YES then the hyperlinks from functions in REFERENCES_RELATION and
@@ -1192,7 +1193,7 @@ DOCSET_FEEDNAME        = "Doxygen generated docs"
 # The default value is: org.doxygen.Project.
 # This tag requires that the tag GENERATE_DOCSET is set to YES.
 
-DOCSET_BUNDLE_ID       = org.doxygen.Project
+DOCSET_BUNDLE_ID       = com.cryptopp.Project
 
 # The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify
 # the documentation publisher. This should be a reverse domain-name style
@@ -1200,13 +1201,13 @@ DOCSET_BUNDLE_ID       = org.doxygen.Project
 # The default value is: org.doxygen.Publisher.
 # This tag requires that the tag GENERATE_DOCSET is set to YES.
 
-DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
+DOCSET_PUBLISHER_ID    = com.cryptopp.Publisher
 
 # The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher.
 # The default value is: Publisher.
 # This tag requires that the tag GENERATE_DOCSET is set to YES.
 
-DOCSET_PUBLISHER_NAME  = Publisher
+DOCSET_PUBLISHER_NAME  = Crypto++
 
 # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three
 # additional HTML index files: index.hhp, index.hhc, and index.hhk. The

algparam.h

@@ -8,8 +8,8 @@
 #ifndef CRYPTOPP_ALGPARAM_H
 #define CRYPTOPP_ALGPARAM_H
 
-#include "cryptlib.h"
 #include "config.h"
+#include "cryptlib.h"
 
 // TODO: fix 6011 when the API/ABI can change
 #if (CRYPTOPP_MSC_VERSION >= 1400)
@@ -24,22 +24,40 @@
 
 NAMESPACE_BEGIN(CryptoPP)
 
-//! used to pass byte array input as part of a NameValuePairs object
+//! \class ConstByteArrayParameter
-/*! the deepCopy option is used when the NameValuePairs object can't
+//! \brief Used to pass byte array input as part of a NameValuePairs object
-	keep a copy of the data available */
 class ConstByteArrayParameter
 {
 public:
+	//! \brief Construct a ConstByteArrayParameter
+	//! \param data a C-String
+	//! \param deepCopy flag indicating whether the data should be copied
+	//! \details The deepCopy option is used when the NameValuePairs object can't
+	//!   keep a copy of the data available
 	ConstByteArrayParameter(const char *data = NULL, bool deepCopy = false)
 		: m_deepCopy(false), m_data(NULL), m_size(0)
 	{
 		Assign((const byte *)data, data ? strlen(data) : 0, deepCopy);
 	}
+
+	//! \brief Construct a ConstByteArrayParameter
+	//! \param data a memory buffer
+	//! \param size the length of the memory buffer
+	//! \param deepCopy flag indicating whether the data should be copied
+	//! \details The deepCopy option is used when the NameValuePairs object can't
+	//!   keep a copy of the data available
 	ConstByteArrayParameter(const byte *data, size_t size, bool deepCopy = false)
 		: m_deepCopy(false), m_data(NULL), m_size(0)
 	{
 		Assign(data, size, deepCopy);
 	}
+
+	//! \brief Construct a ConstByteArrayParameter
+	//! \tparam T a std::basic_string<char> class
+	//! \param string a std::basic_string<char> class
+	//! \param deepCopy flag indicating whether the data should be copied
+	//! \details The deepCopy option is used when the NameValuePairs object can't
+	//!   keep a copy of the data available
 	template <class T> ConstByteArrayParameter(const T &string, bool deepCopy = false)
 		: m_deepCopy(false), m_data(NULL), m_size(0)
 	{
@@ -47,6 +65,12 @@ public:
 		Assign((const byte *)string.data(), string.size(), deepCopy);
 	}
 
+	//! \brief Assign contents from a memory buffer
+	//! \param data a memory buffer
+	//! \param size the length of the memory buffer
+	//! \param deepCopy flag indicating whether the data should be copied
+	//! \details The deepCopy option is used when the NameValuePairs object can't
+	//!   keep a copy of the data available
 	void Assign(const byte *data, size_t size, bool deepCopy)
 	{
 		// This fires, which means: no data with a size, or data with no size.
@@ -61,8 +85,11 @@ public:
 		m_deepCopy = deepCopy;
 	}
 
+	//! \brief Pointer to the first byte in the memory block
 	const byte *begin() const {return m_deepCopy ? m_block.begin() : m_data;}
+	//! \brief Pointer beyond the last byte in the memory block
 	const byte *end() const {return m_deepCopy ? m_block.end() : m_data + m_size;}
+	//! \brief Length of the memory block
 	size_t size() const {return m_deepCopy ? m_block.size() : m_size;}
 
 private:
@@ -72,16 +99,27 @@ private:
 	SecByteBlock m_block;
 };
 
+//! \class ByteArrayParameter
+//! \brief Used to pass byte array input as part of a NameValuePairs object
 class ByteArrayParameter
 {
 public:
+	//! \brief Construct a ByteArrayParameter
+	//! \param data a memory buffer
+	//! \param size the length of the memory buffer
 	ByteArrayParameter(byte *data = NULL, unsigned int size = 0)
 		: m_data(data), m_size(size) {}
+
+	//! \brief Construct a ByteArrayParameter
+	//! \param block a SecByteBlock
 	ByteArrayParameter(SecByteBlock &block)
 		: m_data(block.begin()), m_size(block.size()) {}
 
+	//! \brief Pointer to the first byte in the memory block
 	byte *begin() const {return m_data;}
+	//! \brief Pointer beyond the last byte in the memory block
 	byte *end() const {return m_data + m_size;}
+	//! \brief Length of the memory block
 	size_t size() const {return m_size;}
 
 private:
@@ -89,9 +127,17 @@ private:
 	size_t m_size;
 };
 
+//! \class CombinedNameValuePairs
+//! \brief Combines two sets of NameValuePairs
+//! \details CombinedNameValuePairs allows you to provide two sets of of NameValuePairs.
+//!   If a name is not found in the first set, then the second set is searched for the
+//!   name and value pair. The second set of NameValuePairs often provides default values.
 class CRYPTOPP_DLL CombinedNameValuePairs : public NameValuePairs
 {
 public:
+	//! \brief Construct a CombinedNameValuePairs
+	//! \param pairs1 reference to the first set of NameValuePairs
+	//! \param pairs2 reference to the second set of NameValuePairs
 	CombinedNameValuePairs(const NameValuePairs &pairs1, const NameValuePairs &pairs2)
 		: m_pairs1(pairs1), m_pairs2(pairs2) {}
 
@@ -101,6 +147,7 @@ private:
 	const NameValuePairs &m_pairs1, &m_pairs2;
 };
 
+#ifndef CRYPTOPP_DOXYGEN_PROCESSING
 template <class T, class BASE>
 class GetValueHelperClass
 {
@@ -312,6 +359,8 @@ AssignFromHelperClass<T, T> AssignFromHelper(T *pObject, const NameValuePairs &s
 	return AssignFromHelperClass<T, T>(pObject, source);
 }
 
+#endif // CRYPTOPP_DOXYGEN_PROCESSING
+
 // ********************************************************
 
 // to allow the linker to discard Integer code if not needed.
@@ -320,9 +369,13 @@ CRYPTOPP_DLL extern PAssignIntToInteger g_pAssignIntToInteger;
 
 CRYPTOPP_DLL const std::type_info & CRYPTOPP_API IntegerTypeId();
 
+//! \class AlgorithmParametersBase
+//! \brief Base class for AlgorithmParameters
 class CRYPTOPP_DLL AlgorithmParametersBase
 {
 public:
+	//! \class ParameterNotUsed
+	//! \brief Exception thrown when an AlgorithmParameter is unused
 	class ParameterNotUsed : public Exception
 	{
 	public: 
@@ -337,6 +390,11 @@ public:
 		x.m_used = true;
 	}
 
+	//! \brief Construct a AlgorithmParametersBase
+	//! \param name the parameter name
+	//! \param throwIfNotUsed flags indicating whether an exception should be thrown
+	//! \details If throwIfNotUsed is true, then a ParameterNotUsed exception
+	//!   will be thrown in the destructor if the parameter is not not retrieved.
 	AlgorithmParametersBase(const char *name, bool throwIfNotUsed)
 		: m_name(name), m_throwIfNotUsed(throwIfNotUsed), m_used(false) {}
 
@@ -373,10 +431,19 @@ protected:
 	member_ptr<AlgorithmParametersBase> m_next;
 };
 
+//! \class AlgorithmParametersTemplate
+//! \brief Template base class for AlgorithmParameters
+//! \tparam T the class or type
 template <class T>
 class AlgorithmParametersTemplate : public AlgorithmParametersBase
 {
 public:
+	//! \brief Construct an AlgorithmParametersTemplate
+	//! \param name the name of the value
+	//! \param value a reference to the value
+	//! \param throwIfNotUsed flags indicating whether an exception should be thrown
+	//! \details If throwIfNotUsed is true, then a ParameterNotUsed exception
+	//!   will be thrown in the destructor if the parameter is not not retrieved.
 	AlgorithmParametersTemplate(const char *name, const T &value, bool throwIfNotUsed)
 		: AlgorithmParametersBase(name, throwIfNotUsed), m_value(value)
 	{

seckey.h

@@ -9,8 +9,8 @@
 #include "config.h"
 
 #if CRYPTOPP_MSC_VERSION
-# pragma warning(push)
+# pragma IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements"(push)
-# pragma warning(disable: 4189)
+# pragma IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements"(disable: 4189)
 #endif
 
 #include "cryptlib.h"
@@ -21,7 +21,7 @@ NAMESPACE_BEGIN(CryptoPP)
 
 //! \brief Inverts the cipher's direction
 //! \param dir the cipher's direction
-//! \returns DECRYPTION if dir is ENCRYPTION, DECRYPTION otherwise
+//! \returns DECRYPTION if \ref CipherDir "dir" is ENCRYPTION, DECRYPTION otherwise
 inline CipherDir ReverseCipherDir(CipherDir dir)
 {
 	return (dir == ENCRYPTION) ? DECRYPTION : ENCRYPTION;
@@ -107,8 +107,8 @@ protected:
 //! \class FixedKeyLength
 //! \brief Inherited by keyed algorithms with fixed key length
 //! \tparam N Default key length, in bytes
-//! \tparam IV_REQ The IV requirements. See IV_Requirement in cryptlib.h for allowed values
+//! \tparam IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements"
-//! \tparam IV_L Default IV length, in bytes
+//! \tparam IV_L default IV length, in bytes
 //! \sa SimpleKeyingInterface
 template <unsigned int N, unsigned int IV_REQ = SimpleKeyingInterface::NOT_RESYNCHRONIZABLE, unsigned int IV_L = 0>
 class FixedKeyLength
@@ -147,8 +147,8 @@ public:
 //! \tparam N Minimum key length, in bytes
 //! \tparam M Maximum key length, in bytes
 //! \tparam M Default key length multiple, in bytes. The default multiple is 1.
-//! \tparam IV_REQ The IV requirements. See IV_Requirement in cryptlib.h for allowed values
+//! \tparam IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements"
-//! \tparam IV_L Default IV length, in bytes. The default length is 0.
+//! \tparam IV_L default IV length, in bytes. The default length is 0.
 //! \sa SimpleKeyingInterface
 template <unsigned int D, unsigned int N, unsigned int M, unsigned int Q = 1, unsigned int IV_REQ = SimpleKeyingInterface::NOT_RESYNCHRONIZABLE, unsigned int IV_L = 0>
 class VariableKeyLength
@@ -209,8 +209,8 @@ public:
 //! \class SameKeyLengthAs
 //! \brief Provides key lengths based on another class's key length
 //! \tparam T another FixedKeyLength or VariableKeyLength class
-//! \tparam IV_REQ The IV requirements. See IV_Requirement in cryptlib.h for allowed values
+//! \tparam IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements"
-//! \tparam IV_L Default IV length, in bytes
+//! \tparam IV_L default IV length, in bytes
 //! \sa SimpleKeyingInterface
 template <class T, unsigned int IV_REQ = SimpleKeyingInterface::NOT_RESYNCHRONIZABLE, unsigned int IV_L = 0>
 class SameKeyLengthAs
@@ -247,7 +247,7 @@ public:
 // ************** implementation helper for SimpleKeyingInterface ***************
 
 //! \class SimpleKeyingInterfaceImpl
-//! \brief Provides class member functions to access SimpleKeyingInterface constants
+//! \brief Provides a base implementation of SimpleKeyingInterface
 //! \tparam BASE a SimpleKeyingInterface derived class
 //! \tparam INFO a SimpleKeyingInterface derived class
 //! \sa SimpleKeyingInterface
@@ -293,7 +293,7 @@ public:
 };
 
 //! \class BlockCipherImpl
-//! \brief Provides class member functions to access BlockCipher constants
+//! \brief Provides a base implementation of Algorithm and SimpleKeyingInterface for block ciphers
 //! \tparam INFO a SimpleKeyingInterface derived class
 //! \tparam BASE a SimpleKeyingInterface derived class
 template <class INFO, class BASE = BlockCipher>
@@ -343,12 +343,12 @@ public:
 
 	//! \brief Provides the direction of the cipher
 	//! \returns true if DIR is ENCRYPTION, false otherwise
-	//! \sa IsForwardTransformation(), IsPermutation(), GetCipherDirection()
+	//! \sa GetCipherDirection(), IsPermutation()
 	bool IsForwardTransformation() const {return DIR == ENCRYPTION;}
 };
 
 //! \class MessageAuthenticationCodeImpl
-//! \brief Provides class member functions to access MessageAuthenticationCode constants
+//! \brief Provides a base implementation of Algorithm and SimpleKeyingInterface for message authentication codes
 //! \tparam INFO a SimpleKeyingInterface derived class
 //! \tparam BASE a SimpleKeyingInterface derived class
 template <class BASE, class INFO = BASE>
@@ -430,7 +430,7 @@ struct AuthenticatedSymmetricCipherDocumentation
 NAMESPACE_END
 	
 #if CRYPTOPP_MSC_VERSION
-# pragma warning(pop)
+# pragma IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements"(pop)
 #endif
 
 #endif