From be8bbc26911e941872eb0912bb9c3d3512ceadc5 Mon Sep 17 00:00:00 2001
From: Jeffrey Walton <noloader@gmail.com>
Date: Tue, 12 Jan 2016 12:11:51 -0500
Subject: [PATCH] Updated documentation

---
 base32.h | 34 +++++++++++++++++++++++++++++++---
 base64.h | 45 ++++++++++++++++++++++++++++++++++++---------
 2 files changed, 67 insertions(+), 12 deletions(-)

diff --git a/base32.h b/base32.h
index 6790e59d..27e222c5 100644
--- a/base32.h
+++ b/base32.h
@@ -1,4 +1,4 @@
-// base32.h - written and placed in the public domain by Wei Dai
+// base32.h - written and placed in the public domain by Frank Palazzolo, based on hex.cpp by Wei Dai
 
 //! \file
 //! \brief Classes for Base32Encoder and Base32Decoder
@@ -14,7 +14,6 @@ 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 To specify alternative alpahabet or code, call Initialize() with EncodingLookupArray parameter.
 class Base32Encoder : public SimpleProxyFilter
 {
 public:
@@ -44,24 +43,53 @@ public:
 	//!     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:
+	//!   <pre>
+	//!     Base32Encoder encoder;
+	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+	//!     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);
+	//!     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.
 	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 To specify alternative alpahabet or code, call Initialize() with EncodingLookupArray parameter.
 class Base32Decoder : public BaseN_Decoder
 {
 public:
 	//! \brief Construct a Base32Decoder
 	//! \param attachment a BufferedTrasformation to attach to this object
+	//! \sa IsolatedInitialize() for an example of modifying a Base32Decoder after construction.
 	Base32Decoder(BufferedTransformation *attachment = NULL)
 		: BaseN_Decoder(GetDefaultDecodingLookupArray(), 5, attachment) {}
 
+	//! \brief Initialize or reinitialize this object, without signal propagation
+	//! \param parameters a set of NameValuePairs used to initialize this object
+	//! \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:
+	//!   <pre>
+	//!     int lookup[256];
+	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+	//!     Base32Decoder::InitializeDecodingLookupArray(lookup, ALPHABET, 32, true /*insensitive*/);
+	//!
+	//!     Base32Decoder decoder;
+	//!     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);
+	//!     decoder.IsolatedInitialize(params);
+	//!   </pre>
 	void IsolatedInitialize(const NameValuePairs &parameters);
 
 private:
+	//! \brief Provides the default decoding lookup table
+	//! \return default decoding lookup table
 	static const int * CRYPTOPP_API GetDefaultDecodingLookupArray();
 };
 
diff --git a/base64.h b/base64.h
index 1f2e44db..70c3acde 100644
--- a/base64.h
+++ b/base64.h
@@ -14,7 +14,6 @@ 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 To specify alternative alpahabet or code, call Initialize() with EncodingLookupArray parameter.
 class Base64Encoder : public SimpleProxyFilter
 {
 public:
@@ -24,7 +23,7 @@ public:
 	//! \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 IsolatedInitialize() for an example of modifying a Base64Encoder after construction.
+	//! \sa Base64URLEncoder(), and IsolatedInitialize() for an example of modifying a Base64Encoder after construction.
 	Base64Encoder(BufferedTransformation *attachment = NULL, bool insertLineBreaks = true, int maxLineLength = 72)
 		: SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment)
 	{
@@ -42,36 +41,60 @@ public:
 	//!     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:
+	//!   <pre>
+	//!     Base64Encoder encoder;
+	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+	//!     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);
+	//!     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.
 	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 To specify alternative alpahabet or code, call Initialize() with EncodingLookupArray parameter.
 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.
 	Base64Decoder(BufferedTransformation *attachment = NULL)
 		: BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {}
     
 	//! \brief Initialize or reinitialize this object, without signal propagation
 	//! \param parameters a set of NameValuePairs used to initialize this object
 	//! \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.
+	//!   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 RFC 4868. You can change the to RFC 4868 web safe alphabet
+	//!   by performing the following:
+	//!   <pre>
+	//!     int lookup[256];
+	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+	//!     Base64Decoder::InitializeDecodingLookupArray(lookup, ALPHABET, 64, false);
+	//!
+	//!     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.
 	void IsolatedInitialize(const NameValuePairs &parameters);
-    
+
 private:
+	//! \brief Provides the default decoding lookup table
+	//! \return default decoding lookup table
 	static const int * CRYPTOPP_API GetDecodingLookupArray();
 };
 
 //! \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 To specify alternative alpahabet or code, call Initialize() with EncodingLookupArray parameter.
 class Base64URLEncoder : public SimpleProxyFilter
 {
 public:
@@ -85,7 +108,7 @@ public:
 	//!   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 IsolatedInitialize() for an example of modifying a Base64URLEncoder after construction.
+	//! \sa Base64Encoder(), and IsolatedInitialize() for an example of modifying a Base64URLEncoder after construction.
 	Base64URLEncoder(BufferedTransformation *attachment = NULL, bool insertLineBreaks = false, int maxLineLength = -1)
 		: SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment)
 	{
@@ -102,18 +125,19 @@ public:
 	//!     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.
 	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 To specify alternative alpahabet or code, call Initialize() with EncodingLookupArray parameter.
 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.
 	Base64URLDecoder(BufferedTransformation *attachment = NULL)
 		: BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {}
     
@@ -122,9 +146,12 @@ 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.
 	void IsolatedInitialize(const NameValuePairs &parameters);
     
 private:
+	//! \brief Provides the default decoding lookup table
+	//! \return default decoding lookup table
 	static const int * CRYPTOPP_API GetDecodingLookupArray();
 };