Updated documentation

gf256.h

@@ -1,3 +1,8 @@
+// gf256.h - written and placed in the public domain by Wei Dai
+
+//! \file gf256.h
+//! \brief Classes and functions for schemes over GF(256)
+
 #ifndef CRYPTOPP_GF256_H
 #define CRYPTOPP_GF256_H
 
@@ -6,7 +11,7 @@
 
 NAMESPACE_BEGIN(CryptoPP)
 
-//! GF(256) with polynomial basis
+//! \brief GF(256) with polynomial basis
 class GF256
 {
 public:

gf2_32.h

@@ -1,3 +1,8 @@
+// gf2_32.h - written and placed in the public domain by Wei Dai
+
+//! \file gf2_32.h
+//! \brief Classes and functions for schemes over GF(2^32)
+
 #ifndef CRYPTOPP_GF2_32_H
 #define CRYPTOPP_GF2_32_H
 
@@ -7,7 +12,7 @@
 
 NAMESPACE_BEGIN(CryptoPP)
 
-//! GF(2^32) with polynomial basis
+//! \brief GF(2^32) with polynomial basis
 class GF2_32
 {
 public:

gf2n.h

@@ -1,8 +1,11 @@
+// gf2n.h - written and placed in the public domain by Wei Dai
+
+//! \file gf2n.h
+//! \brief Classes and functions for schemes over GF(2^n)
+
 #ifndef CRYPTOPP_GF2N_H
 #define CRYPTOPP_GF2N_H
 
-/*! \file */
-
 #include "cryptlib.h"
 #include "secblock.h"
 #include "algebra.h"
@@ -13,14 +16,14 @@
 
 NAMESPACE_BEGIN(CryptoPP)
 
-//! Polynomial with Coefficients in GF(2)
+//! \brief Polynomial with Coefficients in GF(2)
 /*!	\nosubgrouping */
 class CRYPTOPP_DLL PolynomialMod2
 {
 public:
 	//! \name ENUMS, EXCEPTIONS, and TYPEDEFS
 	//@{
-		//! divide by zero exception
+		//! \brief Excpetion thrown when divide by zero is encountered
 		class DivideByZero : public Exception
 		{
 		public:
@@ -32,42 +35,48 @@ public:
 
 	//! \name CREATORS
 	//@{
-		//! creates the zero polynomial
+		//! \brief Construct the zero polynomial
 		PolynomialMod2();
-		//! copy constructor
+		//! Copy construct a PolynomialMod2
 		PolynomialMod2(const PolynomialMod2& t);
 
-		//! convert from word
+		//! \brief Construct a PolynomialMod2 from a word
-		/*! value should be encoded with the least significant bit as coefficient to x^0
+		//! \details value should be encoded with the least significant bit as coefficient to x^0
-			and most significant bit as coefficient to x^(WORD_BITS-1)
+		//!   and most significant bit as coefficient to x^(WORD_BITS-1)
-			bitLength denotes how much memory to allocate initially
+		//!   bitLength denotes how much memory to allocate initially
-		*/
 		PolynomialMod2(word value, size_t bitLength=WORD_BITS);
 
-		//! convert from big-endian byte array
+		//! \brief Construct a PolynomialMod2 from big-endian byte array
 		PolynomialMod2(const byte *encodedPoly, size_t byteCount)
 			{Decode(encodedPoly, byteCount);}
 
-		//! convert from big-endian form stored in a BufferedTransformation
+		//! \brief Construct a PolynomialMod2 from big-endian form stored in a BufferedTransformation
 		PolynomialMod2(BufferedTransformation &encodedPoly, size_t byteCount)
 			{Decode(encodedPoly, byteCount);}
 
-		//! create a random polynomial uniformly distributed over all polynomials with degree less than bitcount
+		//! \brief Create a uniformly distributed random polynomial
+		//! \brief Create a random polynomial uniformly distributed over all polynomials with degree less than bitcount
 		PolynomialMod2(RandomNumberGenerator &rng, size_t bitcount)
 			{Randomize(rng, bitcount);}
 
-		//! return x^i
+		//! \brief Provides x^i
+		//! \returns x^i
 		static PolynomialMod2 CRYPTOPP_API Monomial(size_t i);
-		//! return x^t0 + x^t1 + x^t2
+		//! \brief Provides x^t0 + x^t1 + x^t2
+		//! \returns x^t0 + x^t1 + x^t2
 		static PolynomialMod2 CRYPTOPP_API Trinomial(size_t t0, size_t t1, size_t t2);
-		//! return x^t0 + x^t1 + x^t2 + x^t3 + x^t4
+		//! \brief Provides x^t0 + x^t1 + x^t2 + x^t3 + x^t4
+		//! \returns x^t0 + x^t1 + x^t2 + x^t3 + x^t4
 		static PolynomialMod2 CRYPTOPP_API Pentanomial(size_t t0, size_t t1, size_t t2, size_t t3, size_t t4);
-		//! return x^(n-1) + ... + x + 1
+		//! \brief Provides x^(n-1) + ... + x + 1
+		//! \returns x^(n-1) + ... + x + 1
 		static PolynomialMod2 CRYPTOPP_API AllOnes(size_t n);
 
-		//!
+		//! \brief The Zero polinomial
+		//! \returns the zero polynomial
 		static const PolynomialMod2 & CRYPTOPP_API Zero();
-		//!
+		//! \brief The One polinomial
+		//! \returns the one polynomial
 		static const PolynomialMod2 & CRYPTOPP_API One();
 	//@}
 
@@ -78,9 +87,8 @@ public:
 		unsigned int MinEncodedSize() const {return STDMAX(1U, ByteCount());}
 
 		//! encode in big-endian format
-		/*! if outputLen < MinEncodedSize, the most significant bytes will be dropped
+		//! \details if outputLen < MinEncodedSize, the most significant bytes will be dropped
-			if outputLen > MinEncodedSize, the most significant bytes will be padded
+		//!   if outputLen > MinEncodedSize, the most significant bytes will be padded
-		*/
 		void Encode(byte *output, size_t outputLen) const;
 		//!
 		void Encode(BufferedTransformation &bt, size_t outputLen) const;
@@ -278,7 +286,7 @@ CRYPTOPP_DLL_TEMPLATE_CLASS AbstractEuclideanDomain<PolynomialMod2>;
 CRYPTOPP_DLL_TEMPLATE_CLASS EuclideanDomainOf<PolynomialMod2>;
 CRYPTOPP_DLL_TEMPLATE_CLASS QuotientRing<EuclideanDomainOf<PolynomialMod2> >;
 
-//! GF(2^n) with Polynomial Basis
+//! \brief GF(2^n) with Polynomial Basis
 class CRYPTOPP_DLL GF2NP : public QuotientRing<EuclideanDomainOf<PolynomialMod2> >
 {
 public:
@@ -314,7 +322,7 @@ protected:
 	unsigned int m;
 };
 
-//! GF(2^n) with Trinomial Basis
+//! \brief GF(2^n) with Trinomial Basis
 class CRYPTOPP_DLL GF2NT : public GF2NP
 {
 public:
@@ -338,7 +346,7 @@ private:
 	mutable PolynomialMod2 result;
 };
 
-//! GF(2^n) with Pentanomial Basis
+//! \brief GF(2^n) with Pentanomial Basis
 class CRYPTOPP_DLL GF2NPP : public GF2NP
 {
 public: