Update documentation

cryptlib.h

@@ -202,6 +202,9 @@ private:
 class CRYPTOPP_DLL InvalidArgument : public Exception
 {
 public:
+	/// \brief Construct an InvalidArgument
+	/// \param s the message for the exception
+	/// \details The member function <tt>what()</tt> returns <tt>s</tt>.
 	explicit InvalidArgument(const std::string &s) : Exception(INVALID_ARGUMENT, s) {}
 };
 
@@ -209,6 +212,9 @@ public:
 class CRYPTOPP_DLL InvalidDataFormat : public Exception
 {
 public:
+	/// \brief Construct an InvalidDataFormat
+	/// \param s the message for the exception
+	/// \details The member function <tt>what()</tt> returns <tt>s</tt>.
 	explicit InvalidDataFormat(const std::string &s) : Exception(INVALID_DATA_FORMAT, s) {}
 };
 
@@ -216,6 +222,9 @@ public:
 class CRYPTOPP_DLL InvalidCiphertext : public InvalidDataFormat
 {
 public:
+	/// \brief Construct an InvalidCiphertext
+	/// \param s the message for the exception
+	/// \details The member function <tt>what()</tt> returns <tt>s</tt>.
 	explicit InvalidCiphertext(const std::string &s) : InvalidDataFormat(s) {}
 };
 
@@ -223,6 +232,9 @@ public:
 class CRYPTOPP_DLL NotImplemented : public Exception
 {
 public:
+	/// \brief Construct an NotImplemented
+	/// \param s the message for the exception
+	/// \details The member function <tt>what()</tt> returns <tt>s</tt>.
 	explicit NotImplemented(const std::string &s) : Exception(NOT_IMPLEMENTED, s) {}
 };
 
@@ -230,6 +242,9 @@ public:
 class CRYPTOPP_DLL CannotFlush : public Exception
 {
 public:
+	/// \brief Construct an CannotFlush
+	/// \param s the message for the exception
+	/// \details The member function <tt>what()</tt> returns <tt>s</tt>.
 	explicit CannotFlush(const std::string &s) : Exception(CANNOT_FLUSH, s) {}
 };
 
@@ -238,6 +253,13 @@ class CRYPTOPP_DLL OS_Error : public Exception
 {
 public:
 	virtual ~OS_Error() throw() {}
+
+	/// \brief Construct an OS_Error
+	/// \param errorType the error type
+	/// \param s the message for the exception
+	/// \param operation the operation for the exception
+	/// \param errorCode the error code
+	/// \details The member function <tt>what()</tt> returns <tt>s</tt>.
 	OS_Error(ErrorType errorType, const std::string &s, const std::string& operation, int errorCode)
 		: Exception(errorType, s), m_operation(operation), m_errorCode(errorCode) {}
 
@@ -255,7 +277,8 @@ protected:
 struct CRYPTOPP_DLL DecodingResult
 {
 	/// \brief Constructs a DecodingResult
-	/// \details isValidCoding is initialized to false and messageLength is initialized to 0.
+	/// \details isValidCoding is initialized to false and messageLength is
+	///  initialized to 0.
 	explicit DecodingResult() : isValidCoding(false), messageLength(0) {}
 	/// \brief Constructs a DecodingResult
 	/// \param len the message length
@@ -264,11 +287,13 @@ struct CRYPTOPP_DLL DecodingResult
 
 	/// \brief Compare two DecodingResult
 	/// \param rhs the other DecodingResult
-	/// \return true if both isValidCoding and messageLength are equal, false otherwise
+	/// \return true if either isValidCoding or messageLength is \a not equal,
+	///  false otherwise
 	bool operator==(const DecodingResult &rhs) const {return isValidCoding == rhs.isValidCoding && messageLength == rhs.messageLength;}
 	/// \brief Compare two DecodingResult
 	/// \param rhs the other DecodingResult
-	/// \return true if either isValidCoding or messageLength is \a not equal, false otherwise
+	/// \return true if either isValidCoding or messageLength is \a not equal,
+	///  false otherwise
 	/// \details Returns <tt>!operator==(rhs)</tt>.
 	bool operator!=(const DecodingResult &rhs) const {return !operator==(rhs);}
 
@@ -279,24 +304,28 @@ struct CRYPTOPP_DLL DecodingResult
 };
 
 /// \brief Interface for retrieving values given their names
-/// \details This class is used to safely pass a variable number of arbitrarily typed arguments to functions
+/// \details This class is used to safely pass a variable number of arbitrarily
-///   and to read values from keys and crypto parameters.
+///  typed arguments to functions and to read values from keys and crypto parameters.
-/// \details To obtain an object that implements NameValuePairs for the purpose of parameter
+/// \details To obtain an object that implements NameValuePairs for the purpose of
-///   passing, use the MakeParameters() function.
+///  parameter passing, use the MakeParameters() function.
-/// \details To get a value from NameValuePairs, you need to know the name and the type of the value.
+/// \details To get a value from NameValuePairs, you need to know the name and the
-///   Call GetValueNames() on a NameValuePairs object to obtain a list of value names that it supports.
+///  type of the value. Call GetValueNames() on a NameValuePairs object to obtain a
-///   then look at the Name namespace documentation to see what the type of each value is, or
+///  list of value names that it supports. then look at the Name namespace
-///   alternatively, call GetIntValue() with the value name, and if the type is not int, a
+///  documentation to see what the type of each value is, or alternatively, call
-///   ValueTypeMismatch exception will be thrown and you can get the actual type from the exception object.
+///  GetIntValue() with the value name, and if the type is not int, a
+///  ValueTypeMismatch exception will be thrown and you can get the actual type from
+///  the exception object.
 /// \sa NullNameValuePairs, g_nullNameValuePairs,
-///   <A HREF="http://www.cryptopp.com/wiki/NameValuePairs">NameValuePairs</A> on the Crypto++ wiki
+///  <A HREF="http://www.cryptopp.com/wiki/NameValuePairs">NameValuePairs</A> on the
+///  Crypto++ wiki
 class NameValuePairs
 {
 public:
 	virtual ~NameValuePairs() {}
 
 	/// \brief Thrown when an unexpected type is encountered
-	/// \details Exception thrown when trying to retrieve a value using a different type than expected
+	/// \details Exception thrown when trying to retrieve a value using a different
+	///  type than expected
 	class CRYPTOPP_DLL ValueTypeMismatch : public InvalidArgument
 	{
 	public:
@@ -1789,18 +1818,23 @@ public:
 
 		/// \brief Flush buffered input and/or output, with signal propagation
 		/// \param hardFlush is used to indicate whether all data should be flushed
-		/// \param propagation the number of attached transformations the Flush() signal should be passed
+		/// \param propagation the number of attached transformations the Flush()
-		/// \param blocking specifies whether the object should block when processing input
+		///  signal should be passed
-		/// \details propagation count includes this object. Setting propagation to <tt>1</tt> means this
+		/// \param blocking specifies whether the object should block when processing
-		///   object only. Setting propagation to <tt>-1</tt> means unlimited propagation.
+		///  input
-		/// \note Hard flushes must be used with care. It means try to process and output everything, even if
+		/// \details propagation count includes this object. Setting propagation to
-		///   there may not be enough data to complete the action. For example, hard flushing a HexDecoder
+		///  <tt>1</tt> means this object only. Setting propagation to <tt>-1</tt>
-		///   would cause an error if you do it after inputing an odd number of hex encoded characters.
+		///  means unlimited propagation.
-		/// \note For some types of filters, like  ZlibDecompressor, hard flushes can only
+		/// \note Hard flushes must be used with care. It means try to process and
-		///   be done at "synchronization points". These synchronization points are positions in the data
+		///  output everything, even if there may not be enough data to complete the
-		///   stream that are created by hard flushes on the corresponding reverse filters, in this
+		///  action. For example, hard flushing a HexDecoder would cause an error if
-		///   example ZlibCompressor. This is useful when zlib compressed data is moved across a
+		///  you do it after inputing an odd number of hex encoded characters.
-		///   network in packets and compression state is preserved across packets, as in the SSH2 protocol.
+		/// \note For some types of filters, like  ZlibDecompressor, hard flushes can
+		///  only be done at "synchronization points". These synchronization points
+		///  are positions in the data stream that are created by hard flushes on the
+		///  corresponding reverse filters, in this example ZlibCompressor. This is
+		///  useful when zlib compressed data is moved across a network in packets
+		///  and compression state is preserved across packets, as in the SSH2 protocol.
 		virtual bool Flush(bool hardFlush, int propagation=-1, bool blocking=true);
 
 		/// \brief Marks the end of a series of messages, with signal propagation

simple.h

@@ -25,6 +25,9 @@ template <class DERIVED, class BASE>
 class CRYPTOPP_NO_VTABLE ClonableImpl : public BASE
 {
 public:
+	/// \brief Create a copy of this object
+	/// \returns a copy of this object
+	/// \details The caller is responsible for freeing the object.
 	Clonable * Clone() const {return new DERIVED(*static_cast<const DERIVED *>(this));}
 };
 
@@ -52,6 +55,9 @@ public:
 class CRYPTOPP_DLL InvalidKeyLength : public InvalidArgument
 {
 public:
+	/// \brief Construct an InvalidKeyLength
+	/// \param algorithm the Algorithm associated with the exception
+	/// \param length the key size associated with the exception
 	explicit InvalidKeyLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid key length") {}
 };
 
@@ -59,6 +65,9 @@ public:
 class CRYPTOPP_DLL InvalidRounds : public InvalidArgument
 {
 public:
+	/// \brief Construct an InvalidRounds
+	/// \param algorithm the Algorithm associated with the exception
+	/// \param rounds the number of rounds associated with the exception
 	explicit InvalidRounds(const std::string &algorithm, unsigned int rounds) : InvalidArgument(algorithm + ": " + IntToString(rounds) + " is not a valid number of rounds") {}
 };
 
@@ -66,6 +75,9 @@ public:
 class CRYPTOPP_DLL InvalidBlockSize : public InvalidArgument
 {
 public:
+	/// \brief Construct an InvalidBlockSize
+	/// \param algorithm the Algorithm associated with the exception
+	/// \param length the block size associated with the exception
 	explicit InvalidBlockSize(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid block size") {}
 };
 
@@ -73,6 +85,9 @@ public:
 class CRYPTOPP_DLL InvalidDerivedKeyLength : public InvalidArgument
 {
 public:
+	/// \brief Construct an InvalidDerivedKeyLength
+	/// \param algorithm the Algorithm associated with the exception
+	/// \param length the size associated with the exception
 	explicit InvalidDerivedKeyLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid derived key length") {}
 };
 
@@ -80,6 +95,9 @@ public:
 class CRYPTOPP_DLL InvalidPersonalizationLength : public InvalidArgument
 {
 public:
+	/// \brief Construct an InvalidPersonalizationLength
+	/// \param algorithm the Algorithm associated with the exception
+	/// \param length the personalization size associated with the exception
 	explicit InvalidPersonalizationLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid salt length") {}
 };
 
@@ -87,6 +105,9 @@ public:
 class CRYPTOPP_DLL InvalidSaltLength : public InvalidArgument
 {
 public:
+	/// \brief Construct an InvalidSaltLength
+	/// \param algorithm the Algorithm associated with the exception
+	/// \param length the salt size associated with the exception
 	explicit InvalidSaltLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid salt length") {}
 };
 
@@ -98,6 +119,10 @@ template <class T>
 class CRYPTOPP_NO_VTABLE Bufferless : public T
 {
 public:
+	/// \brief Flushes data buffered by this object, without signal propagation
+	/// \param hardFlush indicates whether all data should be flushed
+	/// \param blocking specifies whether the object should block when processing input
+	/// \note hardFlush must be used with care
 	bool IsolatedFlush(bool hardFlush, bool blocking)
 		{CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); return false;}
 };
@@ -108,10 +133,45 @@ template <class T>
 class CRYPTOPP_NO_VTABLE Unflushable : public T
 {
 public:
+	/// \brief Flush buffered input and/or output, with signal propagation
+	/// \param hardFlush is used to indicate whether all data should be flushed
+	/// \param propagation the number of attached transformations the Flush()
+	///  signal should be passed
+	/// \param blocking specifies whether the object should block when processing
+	///  input
+	/// \details propagation count includes this object. Setting propagation to
+	///  <tt>1</tt> means this object only. Setting propagation to <tt>-1</tt>
+	///  means unlimited propagation.
+	/// \note Hard flushes must be used with care. It means try to process and
+	///  output everything, even if there may not be enough data to complete the
+	///  action. For example, hard flushing a HexDecoder would cause an error if
+	///  you do it after inputing an odd number of hex encoded characters.
+	/// \note For some types of filters, like  ZlibDecompressor, hard flushes can
+	///  only be done at "synchronization points". These synchronization points
+	///  are positions in the data stream that are created by hard flushes on the
+	///  corresponding reverse filters, in this example ZlibCompressor. This is
+	///  useful when zlib compressed data is moved across a network in packets
+	///  and compression state is preserved across packets, as in the SSH2 protocol.
 	bool Flush(bool completeFlush, int propagation=-1, bool blocking=true)
 		{return ChannelFlush(DEFAULT_CHANNEL, completeFlush, propagation, blocking);}
+
+	/// \brief Flushes data buffered by this object, without signal propagation
+	/// \param hardFlush indicates whether all data should be flushed
+	/// \param blocking specifies whether the object should block when processing input
+	/// \note hardFlush must be used with care
 	bool IsolatedFlush(bool hardFlush, bool blocking)
 		{CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); CRYPTOPP_ASSERT(false); return false;}
+
+	/// \brief Flush buffered input and/or output on a channel
+	/// \param channel the channel to flush the data
+	/// \param hardFlush is used to indicate whether all data should be flushed
+	/// \param propagation the number of attached transformations the ChannelFlush()
+	///  signal should be passed
+	/// \param blocking specifies whether the object should block when processing input
+	/// \return true of the Flush was successful
+	/// \details propagation count includes this object. Setting propagation to
+	///  <tt>1</tt> means this object only. Setting propagation to <tt>-1</tt> means
+	///  unlimited propagation.
 	bool ChannelFlush(const std::string &channel, bool hardFlush, int propagation=-1, bool blocking=true)
 	{
 		if (hardFlush && !InputBufferIsEmpty())