Updated documentation (Issue 328)

eccrypto.h

@@ -181,8 +181,22 @@ public:
 		{this->AccessGroupParameters() = params; this->SetPrivateExponent(x);}
 	void Initialize(const EC &ec, const Element &G, const Integer &n, const Integer &x)
 		{this->AccessGroupParameters().Initialize(ec, G, n); this->SetPrivateExponent(x);}
+	//! \brief Create an EC private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param params the EC group parameters
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, const DL_GroupParameters_EC<EC> &params)
 		{this->GenerateRandom(rng, params);}
+	//! \brief Create an EC private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param ec the elliptic curve
+	//! \param G the base point
+	//! \param n the cofactor
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, const EC &ec, const Element &G, const Integer &n)
 		{this->GenerateRandom(rng, DL_GroupParameters_EC<EC>(ec, G, n));}
 

esign.h

@@ -64,7 +64,13 @@ class InvertibleESIGNFunction : public ESIGNFunction, public RandomizedTrapdoorF
 public:
 	void Initialize(const Integer &n, const Integer &e, const Integer &p, const Integer &q)
 		{m_n = n; m_e = e; m_p = p; m_q = q;}
-	// generate a random private key
+
+	//! \brief Create a RSA private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param modulusBits the size of the modulud, in bits
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits)
 		{GenerateRandomWithKeySize(rng, modulusBits);}
 

gfpcrypt.h

@@ -39,6 +39,12 @@ public:
 
 	void Initialize(const DL_GroupParameters_IntegerBased &params)
 		{Initialize(params.GetModulus(), params.GetSubgroupOrder(), params.GetSubgroupGenerator());}
+	//! \brief Create a trapdoor function keypair
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param pbits the size of p, in bits
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, unsigned int pbits)
 		{GenerateRandom(rng, MakeParameters("ModulusSize", (int)pbits));}
 	void Initialize(const Integer &p, const Integer &g)
@@ -271,14 +277,39 @@ class DL_PrivateKey_GFP : public DL_PrivateKeyImpl<GP>
 public:
 	virtual ~DL_PrivateKey_GFP() {}
 
+	//! \brief Create a private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param modulusBits the size of the modulus, in bits
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits)
 		{this->GenerateRandomWithKeySize(rng, modulusBits);}
+
+	//! \brief Create a private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param p TODO
+	//! \param g TODO
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, const Integer &p, const Integer &g)
 		{this->GenerateRandom(rng, MakeParameters("Modulus", p)("SubgroupGenerator", g));}
+
+	//! \brief Create a private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param p TODO
+	//! \param q TODO
+	//! \param g TODO
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, const Integer &p, const Integer &q, const Integer &g)
 		{this->GenerateRandom(rng, MakeParameters("Modulus", p)("SubgroupOrder", q)("SubgroupGenerator", g));}
+
 	void Initialize(const DL_GroupParameters_IntegerBased &params, const Integer &x)
 		{this->AccessGroupParameters().Initialize(params); this->SetPrivateExponent(x);}
+
 	void Initialize(const Integer &p, const Integer &g, const Integer &x)
 		{this->AccessGroupParameters().Initialize(p, g); this->SetPrivateExponent(x);}
 	void Initialize(const Integer &p, const Integer &q, const Integer &g, const Integer &x)

luc.h

@@ -76,6 +76,14 @@ class InvertibleLUCFunction : public LUCFunction, public TrapdoorFunctionInverse
 public:
 	virtual ~InvertibleLUCFunction() {}
 
+	//! \brief Create a LUC private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param modulusBits the size of the modulus, in bits
+	//! \param eStart the desired starting public exponent
+	//! \details Initialize() creates a new keypair using a starting public exponent of 17.
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits, const Integer &eStart=17);
 	void Initialize(const Integer &n, const Integer &e, const Integer &p, const Integer &q, const Integer &u)
 		{m_n = n; m_e = e; m_p = p; m_q = q; m_u = u;}

rabin.h

@@ -13,7 +13,9 @@
 
 NAMESPACE_BEGIN(CryptoPP)
 
-//! _
+//! \class RabinFunction
+//! \brief Rabin trapdoor function using the public key
+//! \since Crypto++ 2.0
 class RabinFunction : public TrapdoorFunction, public PublicKey
 {
 	typedef RabinFunction ThisClass;
@@ -45,7 +47,9 @@ protected:
 	Integer m_n, m_r, m_s;
 };
 
-//! _
+//! \class InvertibleRabinFunction
+//! \brief Rabin trapdoor function using the private key
+//! \since Crypto++ 2.0
 class InvertibleRabinFunction : public RabinFunction, public TrapdoorFunctionInverse, public PrivateKey
 {
 	typedef InvertibleRabinFunction ThisClass;
@@ -54,6 +58,13 @@ public:
 	void Initialize(const Integer &n, const Integer &r, const Integer &s,
 							const Integer &p, const Integer &q, const Integer &u)
 		{m_n = n; m_r = r; m_s = s; m_p = p; m_q = q; m_u = u;}
+
+	//! \brief Create a Rabin private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param keybits the size of the key, in bits
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, unsigned int keybits)
 		{GenerateRandomWithKeySize(rng, keybits);}
 
@@ -80,7 +91,7 @@ protected:
 	Integer m_p, m_q, m_u;
 };
 
-//! Rabin
+//! \brief Rabin keys
 struct Rabin
 {
 	static std::string StaticAlgorithmName() {return "Rabin-Crypto++Variant";}
@@ -88,13 +99,16 @@ struct Rabin
 	typedef InvertibleRabinFunction PrivateKey;
 };
 
-//! Rabin encryption
+//! \brief Rabin encryption scheme
+//! \tparam STANDARD encryption standard
 template <class STANDARD>
 struct RabinES : public TF_ES<Rabin, STANDARD>
 {
 };
 
-//! Rabin signature
+//! \brief Rabin signature scheme
+//! \tparam STANDARD signature standard
+//! \tparam H hash transformation
 template <class STANDARD, class H>
 struct RabinSS : public TF_SS<Rabin, STANDARD, H>
 {

rsa.h

@@ -68,8 +68,12 @@ class CRYPTOPP_DLL InvertibleRSAFunction : public RSAFunction, public TrapdoorFu
 public:
 	//! \brief Create a RSA private key
 	//! \param rng a RandomNumberGenerator derived class
-	//! \param modulusBits the size of the modulud, in bits
+	//! \param modulusBits the size of the modulus, in bits
 	//! \param e the desired public exponent
+	//! \details Initialize() creates a new keypair using a public exponent of 17.
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits, const Integer &e = 17);
 
 	//! \brief Initialize a RSA private key with {n,e,d,p,q,dp,dq,u}
@@ -83,6 +87,7 @@ public:
 	//! \param u q<sup>-1</sup> mod p
 	void Initialize(const Integer &n, const Integer &e, const Integer &d, const Integer &p, const Integer &q, const Integer &dp, const Integer &dq, const Integer &u)
 		{m_n = n; m_e = e; m_d = d; m_p = p; m_q = q; m_dp = dp; m_dq = dq; m_u = u;}
+
 	//! \brief Initialize a RSA private key with {n,e,d}
 	//! \param n modulus
 	//! \param e public exponent

rw.h

@@ -19,6 +19,7 @@ NAMESPACE_BEGIN(CryptoPP)
 
 //! \class RWFunction
 //! \brief Rabin-Williams trapdoor function using the public key
+//! \since Crypto++ 2.0, Tweaked roots using <em>e</em> and <em>f</em> since Crypto++ 5.6.4
 class CRYPTOPP_DLL RWFunction : public TrapdoorFunction, public PublicKey
 {
 	typedef RWFunction ThisClass;
@@ -52,7 +53,7 @@ protected:
 
 //! \class InvertibleRWFunction
 //! \brief Rabin-Williams trapdoor function using the private key
-//! \since Tweaked roots using <em>e</em> and <em>f</em> since Crypto++ 5.6.4
+//! \since Crypto++ 2.0, Tweaked roots using <em>e</em> and <em>f</em> since Crypto++ 5.6.4
 class CRYPTOPP_DLL InvertibleRWFunction : public RWFunction, public TrapdoorFunctionInverse, public PrivateKey
 {
 	typedef InvertibleRWFunction ThisClass;
@@ -61,7 +62,13 @@ public:
 	InvertibleRWFunction() : m_precompute(false) {}
 
 	void Initialize(const Integer &n, const Integer &p, const Integer &q, const Integer &u);
-	// generate a random private key
+
+	//! \brief Create a Rabin-Williams private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param modulusBits the size of the modulus, in bits
+	//! \details This function overload of Initialize() creates a new keypair because it
+	//!   takes a RandomNumberGenerator() as a parameter. If you have an existing keypair,
+	//!   then use one of the other Initialize() overloads.
 	void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits)
 		{GenerateRandomWithKeySize(rng, modulusBits);}
 
@@ -107,17 +114,17 @@ protected:
 	mutable bool m_precompute;
 };
 
-//! \class RW
-//! \brief Rabin-Williams algorithm
+//! \brief Rabin-Williams keys
 struct RW
 {
-	static std::string StaticAlgorithmName() {return "RW";}
+	CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "RW";}
 	typedef RWFunction PublicKey;
 	typedef InvertibleRWFunction PrivateKey;
 };
 
-//! \class RWSS
 //! \brief Rabin-Williams signature scheme
+//! \tparam STANDARD signature standard
+//! \tparam H hash transformation
 template <class STANDARD, class H>
 struct RWSS : public TF_SS<RW, STANDARD, H>
 {