From a991b29f97d10b6ebf859b33dcfa5efb79a82be1 Mon Sep 17 00:00:00 2001
From: Jeffrey Walton <noloader@gmail.com>
Date: Sun, 17 Jan 2016 12:48:28 -0500
Subject: [PATCH] Updated documentation

---
 base32.h   | 28 +++++++++++++--------------
 base64.h   | 56 ++++++++++++++++++++++++++++--------------------------
 cryptlib.h |  2 ++
 rng.h      | 10 +++++-----
 4 files changed, 49 insertions(+), 47 deletions(-)

diff --git a/base32.h b/base32.h
index 27e222c5..05d68764 100644
--- a/base32.h
+++ b/base32.h
@@ -13,7 +13,7 @@ NAMESPACE_BEGIN(CryptoPP)
 
 //! \class Base32Encoder
 //! \brief Base32 encodes data
-//! \details Converts data to base32. The default code is based on draft-ietf-idn-dude-02.txt.
+//! \details Converts data to base32. The default code is based on <A HREF="http://www.ietf.org/proceedings/51/I-D/draft-ietf-idn-dude-02.txt">Differential Unicode Domain Encoding (DUDE) (draft-ietf-idn-dude-02.txt)</A>.
 class Base32Encoder : public SimpleProxyFilter
 {
 public:
@@ -41,25 +41,23 @@ public:
 	//!   <pre>
 	//!     Base32Encoder encoder;
 	//!     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);
-	//!     encoder.IsolatedInitialize(params);
-	//!   </pre>
-	//! \details The default encoding alpahbet is DUDE. You can change the encoding to RFC 4648 alphabet by
-	//!   performing the following:
+	//!     encoder.IsolatedInitialize(params);</pre>
+	//! \details You can change the encoding to <A HREF="http://tools.ietf.org/html/rfc4648#page-10">RFC 4648, Base
+	//!   32 Encoding with Extended Hex Alphabet</A> by performing the following:
 	//!   <pre>
 	//!     Base32Encoder encoder;
-	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+	//!     const byte ALPHABET[] = "0123456789ABCDEFGHIJKLMNOPQRSTUV";
 	//!     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);
-	//!     encoder.IsolatedInitialize(params);
-	//!   </pre>
+	//!     encoder.IsolatedInitialize(params);</pre>
 	//! \details If you change the encoding alphabet, then you will need to change the decoding alphabet \a and
 	//!   the decoder's lookup table.
-	//! \sa IsolatedInitialize() for an example of modifying a Base32Encoder after construction.
+	//! \sa Base32Decoder::IsolatedInitialize() for an example of changing a Base32Decoder's lookup table.
 	void IsolatedInitialize(const NameValuePairs &parameters);
 };
 
 //! \class Base32Decoder
 //! \brief Base32 decodes data
-//! \details Decode base32 data. The default code is based on draft-ietf-idn-dude-02.txt
+//! \details Decode base32 data. The default code is based on <A HREF="http://www.ietf.org/proceedings/51/I-D/draft-ietf-idn-dude-02.txt">Differential Unicode Domain Encoding (DUDE) (draft-ietf-idn-dude-02.txt)</A>.
 class Base32Decoder : public BaseN_Decoder
 {
 public:
@@ -74,17 +72,17 @@ public:
 	//! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable
 	//!   number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached
 	//!   transformations. If initialization should be propagated, then use the Initialize() function.
-	//! \details The default decoding alpahbet is DUDE. You can change the to RFC 4868 alphabet by
-	//!   performing the following:
+	//! \details You can change the encoding to <A HREF="http://tools.ietf.org/html/rfc4648#page-10">RFC 4648, Base
+	//!   32 Encoding with Extended Hex Alphabet</A> by performing the following:
 	//!   <pre>
 	//!     int lookup[256];
-	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+	//!     const byte ALPHABET[] = "0123456789ABCDEFGHIJKLMNOPQRSTUV";
 	//!     Base32Decoder::InitializeDecodingLookupArray(lookup, ALPHABET, 32, true /*insensitive*/);
 	//!
 	//!     Base32Decoder decoder;
 	//!     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);
-	//!     decoder.IsolatedInitialize(params);
-	//!   </pre>
+	//!     decoder.IsolatedInitialize(params);</pre>
+	//! \sa Base32Encoder::IsolatedInitialize() for an example of changing a Base32Encoder's alphabet.
 	void IsolatedInitialize(const NameValuePairs &parameters);
 
 private:
diff --git a/base64.h b/base64.h
index 70c3acde..6f6fd51f 100644
--- a/base64.h
+++ b/base64.h
@@ -13,7 +13,7 @@ NAMESPACE_BEGIN(CryptoPP)
 
 //! \class Base64Encoder
 //! \brief Base64 encodes data
-//! \details Base64 encodes data per RFC 4648 (http://tools.ietf.org/html/rfc4648#section-4)
+//! \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-4">RFC 4648, Base 64 Encoding</A>.
 class Base64Encoder : public SimpleProxyFilter
 {
 public:
@@ -21,9 +21,9 @@ public:
 	//! \param attachment a BufferedTrasformation to attach to this object
 	//! \param insertLineBreaks a BufferedTrasformation to attach to this object
 	//! \param maxLineLength the lenght of a line if line breaks are used
-	//! \details Base64Encoder() constructs a default encoder. The constructor lacks parameters for padding.
-	//!    You must use IsolatedInitialize() to modify the Base64Encoder after construction.
-	//! \sa Base64URLEncoder(), and IsolatedInitialize() for an example of modifying a Base64Encoder after construction.
+	//! \details Base64Encoder constructs a default encoder. The constructor lacks a parameter for padding, and you must
+	//!   use IsolatedInitialize() to modify the Base64Encoder after construction.
+	//! \sa IsolatedInitialize() for an example of modifying an encoder after construction.
 	Base64Encoder(BufferedTransformation *attachment = NULL, bool insertLineBreaks = true, int maxLineLength = 72)
 		: SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment)
 	{
@@ -39,31 +39,29 @@ public:
 	//!   <pre>
 	//!     Base64Encoder encoder;
 	//!     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);
-	//!     encoder.IsolatedInitialize(params);
-	//!   </pre>
-	//! \details The default encoding alpahbet is DUDE. You can change the encoding to RFC 4648 web safe alphabet
-	//!   by performing the following:
+	//!     encoder.IsolatedInitialize(params);</pre>
+	//! \details You can change the encoding to RFC 4648 web safe alphabet by performing the following:
 	//!   <pre>
 	//!     Base64Encoder encoder;
 	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 	//!     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);
-	//!     encoder.IsolatedInitialize(params);
-	//!   </pre>
+	//!     encoder.IsolatedInitialize(params);</pre>
 	//! \details If you change the encoding alphabet, then you will need to change the decoding alphabet \a and
 	//!   the decoder's lookup table.
-	//! \sa Base64URLEncoder(), and IsolatedInitialize() for an example of modifying a Base64Encoder after construction.
+	//! \sa Base64URLEncoder for an encoder that provides the web safe alphabet, and Base64Decoder::IsolatedInitialize()
+	//!   for an example of modifying a decoder's lookup table after construction.
 	void IsolatedInitialize(const NameValuePairs &parameters);
 };
 
 //! \class Base64Decoder
 //! \brief Base64 decodes data
-//! \details Base64 decodes data per RFC 4648 (http://tools.ietf.org/html/rfc4648#section-4)
+//! \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-4">RFC 4648, Base 64 Encoding</A>.
 class Base64Decoder : public BaseN_Decoder
 {
 public:
 	//! \brief Construct a Base64Decoder
 	//! \param attachment a BufferedTrasformation to attach to this object
-	//! \sa Base64URLDecoder(), and IsolatedInitialize() for an example of modifying a Base64Decoder after construction.
+	//! \sa IsolatedInitialize() for an example of modifying an encoder after construction.
 	Base64Decoder(BufferedTransformation *attachment = NULL)
 		: BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {}
     
@@ -81,9 +79,9 @@ public:
 	//!
 	//!     Base64Decoder decoder;
 	//!     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);
-	//!     decoder.IsolatedInitialize(params);
-	//!   </pre>
-	//! \sa Base64URLDecoder(), and IsolatedInitialize() for an example of modifying a Base64Decoder after construction.
+	//!     decoder.IsolatedInitialize(params);</pre>
+	//! \sa Base64URLDecoder for a decoder that provides the web safe alphabet, and Base64Encoder::IsolatedInitialize()
+	//!   for an example of modifying an encoder's alphabet after construction.
 	void IsolatedInitialize(const NameValuePairs &parameters);
 
 private:
@@ -94,7 +92,8 @@ private:
 
 //! \class Base64URLEncoder
 //! \brief Base64 encodes data using a web safe alphabet
-//! \details Base64 encodes data using a web safe alphabet per RFC 4648 (http://tools.ietf.org/html/rfc4648#section-5)
+//! \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-5">RFC 4648, Base 64 Encoding
+//!   with URL and Filename Safe Alphabet</A>.
 class Base64URLEncoder : public SimpleProxyFilter
 {
 public:
@@ -102,13 +101,14 @@ public:
 	//! \param attachment a BufferedTrasformation to attach to this object
 	//! \param insertLineBreaks a BufferedTrasformation to attach to this object
 	//! \param maxLineLength the lenght of a line if line breaks are used
-	//! \details Base64URLEncoder() constructs a default encoder. The constructor ignores insertLineBreaks
-	//!   and maxLineLength because the web and URL safe specifications don't use them. They are present
-	//!   in the constructor for API compatibility with Base64Encoder (drop-in replacement). The
+	//! \details Base64URLEncoder() constructs a default encoder using a web safe alphabet. The constructor ignores
+	//!   insertLineBreaks and maxLineLength because the web and URL safe specifications don't use them. They are
+	//!   present in the constructor for API compatibility with Base64Encoder so it is a drop-in replacement. The
 	//!   constructor also disables padding on the encoder for the same reason.
 	//! \details If you need line breaks or padding, then you must use IsolatedInitialize() to set them
 	//!   after constructing a Base64URLEncoder.
-	//! \sa Base64Encoder(), and IsolatedInitialize() for an example of modifying a Base64URLEncoder after construction.
+	//! \sa Base64Encoder for an encoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize
+	//!   for an example of modifying an encoder after construction.
 	Base64URLEncoder(BufferedTransformation *attachment = NULL, bool insertLineBreaks = false, int maxLineLength = -1)
 		: SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment)
 	{
@@ -123,21 +123,22 @@ public:
 	//!   <pre>
 	//!     Base64URLEncoder encoder;
 	//!     AlgorithmParameters params = MakeParameters(Name::Pad(), true)(Name::InsertLineBreaks(), true);
-	//!     encoder.IsolatedInitialize(params);
-	//!   </pre>
-	//! \sa Base64Encoder(), and IsolatedInitialize() for an example of modifying a Base64URLEncoder after construction.
+	//!     encoder.IsolatedInitialize(params);</pre>
+	//! \sa Base64Encoder for an encoder that provides a classic alphabet.
 	void IsolatedInitialize(const NameValuePairs &parameters);
 };
 
 //! \class Base64URLDecoder
 //! \brief Base64 decodes data using a web safe alphabet
-//! \details Base64 decodes data using a web safe alphabet per RFC 4648 (http://tools.ietf.org/html/rfc4648#section-5)
+//! \details Base64 encodes data per <A HREF="http://tools.ietf.org/html/rfc4648#section-5">RFC 4648, Base 64 Encoding
+//!   with URL and Filename Safe Alphabet</A>.
 class Base64URLDecoder : public BaseN_Decoder
 {
 public:
 	//! \brief Construct a Base64URLDecoder
 	//! \param attachment a BufferedTrasformation to attach to this object
-	//! \sa Base64Decoder(), and IsolatedInitialize() for an example of modifying a Base64Decoder() after construction.
+	//! \details Base64URLDecoder() constructs a default decoder using a web safe alphabet.
+	//! \sa Base64Decoder for a decoder that provides a classic alphabet.
 	Base64URLDecoder(BufferedTransformation *attachment = NULL)
 		: BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {}
     
@@ -146,7 +147,8 @@ public:
 	//! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable
 	//!   number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on
 	//!  attached transformations. If initialization should be propagated, then use the Initialize() function.
-	//! \sa Base64Decoder(), and IsolatedInitialize() for an example of modifying a Base64Decoder() after construction.
+	//! \sa Base64Decoder for a decoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize
+	//!   for an example of modifying an encoder after construction.
 	void IsolatedInitialize(const NameValuePairs &parameters);
     
 private:
diff --git a/cryptlib.h b/cryptlib.h
index 1c72b24a..191e6bb9 100644
--- a/cryptlib.h
+++ b/cryptlib.h
@@ -2579,6 +2579,7 @@ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Verifier : public PK_SignatureScheme, p
 {
 public:
 	//! \brief Create a new HashTransformation to accumulate the message to be verified
+	//! \return a pointer to a PK_MessageAccumulator
 	//! \details NewVerificationAccumulator() can be used with all verification methods. Verify() will autimatically delete
 	//!   the accumulator pointer. The caller is responsible for deletion if a method is called that takes a reference.
 	virtual PK_MessageAccumulator * NewVerificationAccumulator() const =0;
@@ -2591,6 +2592,7 @@ public:
 
 	//! \brief Check whether messageAccumulator contains a valid signature and message
 	//! \param messageAccumulator a pointer to a PK_MessageAccumulator derived class
+	//! \return true if the signature is valid, false otherwise
 	//! \details Verify() deletes the messageAccumulator, even if an exception is thrown.
 	virtual bool Verify(PK_MessageAccumulator *messageAccumulator) const;
 
diff --git a/rng.h b/rng.h
index b10f69ea..4a070857 100644
--- a/rng.h
+++ b/rng.h
@@ -42,7 +42,8 @@ private:
 
 //! \class X917RNG
 //! \brief ANSI X9.17 RNG
-//! \details X917RNG is from ANSI X9.17 Appendix C.
+//! \details X917RNG is from ANSI X9.17 Appendix C, and it uses a 64-bit block cipher, like TripleDES.
+//!   If you use a 128-bit block cipher, like AES, then you are effectively using an ANSI X9.31 generator.
 //! \sa AutoSeededX917RNG, DefaultAutoSeededRNG
 class CRYPTOPP_DLL X917RNG : public RandomNumberGenerator, public NotCopyable
 {
@@ -54,15 +55,14 @@ public:
 	//! \details <tt>cipher</tt> will be deleted by the destructor. <tt>seed</tt> must be at least
 	//!   BlockSize() in length. <tt>deterministicTimeVector = 0</tt> means obtain time vector
 	//!   from the system.
-	//! \details When constructing an AutoSeededX917RNG, the generator must be keyed or an
-	//!   access violation will occur because the time vector is encrypted using the block cipher.
+	//! \details When constructing a X917RNG, the generator must be keyed or an access
+	//!   violation will occur because the time vector is encrypted using the block cipher.
 	//!   To key the generator during constructions, perform the following:
 	//! <pre>
 	//!   SecByteBlock key(AES::DEFAULT_KEYLENGTH), seed(AES::BLOCKSIZE);
 	//!   OS_GenerateRandomBlock(false, key, key.size());
 	//!   OS_GenerateRandomBlock(false, seed, seed.size());
-	//!   X917RNG prng(new AES::Encryption(key, AES::DEFAULT_KEYLENGTH), seed, NULL);
-	//! </pre>
+	//!   X917RNG prng(new AES::Encryption(key, AES::DEFAULT_KEYLENGTH), seed, NULL);</pre>
 	//! \sa AutoSeededX917RNG
 	X917RNG(BlockTransformation *cipher, const byte *seed, const byte *deterministicTimeVector = 0);