From a20192a0cedbec8fa30341fcba25becfb87877b9 Mon Sep 17 00:00:00 2001
From: Jeffrey Walton <noloader@gmail.com>
Date: Fri, 8 Apr 2016 17:34:15 -0400
Subject: [PATCH] Updated documentation

---
 asn.h    |  8 ++++++--
 pubkey.h | 10 +++++++---
 rsa.h    | 23 ++++++++++++++++++++++-
 3 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/asn.h b/asn.h
index 3be4aac9..41d518bb 100644
--- a/asn.h
+++ b/asn.h
@@ -379,13 +379,15 @@ public:
 		{BERDecode(bt);}
 };
 
-//! encodes/decodes subjectPublicKeyInfo
+//! \brief Encodes and decodes subjectPublicKeyInfo
 class CRYPTOPP_DLL X509PublicKey : public ASN1CryptoMaterial<PublicKey>
 {
 public:
 	void BERDecode(BufferedTransformation &bt);
 	void DEREncode(BufferedTransformation &bt) const;
 
+	//! \brief Retrieves the OID of the algorithm
+	//! \returns OID of the algorithm
 	virtual OID GetAlgorithmID() const =0;
 	virtual bool BERDecodeAlgorithmParameters(BufferedTransformation &bt)
 		{BERDecodeNull(bt); return false;}
@@ -398,13 +400,15 @@ public:
 	virtual void DEREncodePublicKey(BufferedTransformation &bt) const =0;
 };
 
-//! encodes/decodes privateKeyInfo
+//! \brief Encodes and decodesprivateKeyInfo
 class CRYPTOPP_DLL PKCS8PrivateKey : public ASN1CryptoMaterial<PrivateKey>
 {
 public:
 	void BERDecode(BufferedTransformation &bt);
 	void DEREncode(BufferedTransformation &bt) const;
 
+	//! \brief Retrieves the OID of the algorithm
+	//! \returns OID of the algorithm
 	virtual OID GetAlgorithmID() const =0;
 	virtual bool BERDecodeAlgorithmParameters(BufferedTransformation &bt)
 		{BERDecodeNull(bt); return false;}
diff --git a/pubkey.h b/pubkey.h
index 965dcb56..a91df165 100644
--- a/pubkey.h
+++ b/pubkey.h
@@ -1,8 +1,5 @@
 // pubkey.h - written and placed in the public domain by Wei Dai
 
-#ifndef CRYPTOPP_PUBKEY_H
-#define CRYPTOPP_PUBKEY_H
-
 //! \file pubkey.h
 //! \brief This file contains helper classes/functions for implementing public key algorithms.
 //! \details The class hierachies in this header file tend to look like this:
@@ -34,6 +31,9 @@
 //! \details The \p TF_ prefix means an implementation using trapdoor functions on integers.
 //! \details The \p DL_ prefix means an implementation using group operations (in groups where discrete log is hard).
 
+#ifndef CRYPTOPP_PUBKEY_H
+#define CRYPTOPP_PUBKEY_H
+
 #include "config.h"
 
 #if CRYPTOPP_MSC_VERSION
@@ -201,6 +201,10 @@ public:
 	//! \details If \p IsRandomized() returns \p false, then \p NullRNG() can be used.
 	bool IsRandomized() const {return false;}
 
+	//! \brief Calculates the inverse of an element
+	//! \param rng a \p RandomNumberGenerator derived class
+	//! \param x the element
+	//! \returns the inverse of the element in the group
 	virtual Integer CalculateInverse(RandomNumberGenerator &rng, const Integer &x) const =0;
 };
 
diff --git a/rsa.h b/rsa.h
index ad2b10e8..b9d97b7f 100644
--- a/rsa.h
+++ b/rsa.h
@@ -25,6 +25,9 @@ class CRYPTOPP_DLL RSAFunction : public TrapdoorFunction, public X509PublicKey
 	typedef RSAFunction ThisClass;
 
 public:
+	//! \brief Initialize a RSA public key with {n,e}
+	//! \param n the modulus
+	//! \param e the public exponent
 	void Initialize(const Integer &n, const Integer &e)
 		{m_n = n; m_e = e;}
 
@@ -61,10 +64,28 @@ class CRYPTOPP_DLL InvertibleRSAFunction : public RSAFunction, public TrapdoorFu
 	typedef InvertibleRSAFunction ThisClass;
 
 public:
+	//! \brief Create a RSA private key
+	//! \param rng a RandomNumberGenerator derived class
+	//! \param modulusBits the size of the modulud, in bits
+	//! \param e the desired public exponent
 	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}
+	//! \param n modulus
+	//! \param e public exponent
+	//! \param d private exponent
+	//! \param p first prime factor
+	//! \param q second prime factor
+	//! \param dp d mod p
+	//! \param dq d mod q
+	//! \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;}
-	//! factor n given private exponent
+	//! \brief Initialize a RSA private key with {n,e,d}
+	//! \param n modulus
+	//! \param e public exponent
+	//! \param d private exponent
+	//! \details Initialize() will factor n using d and populate {p,q,dp,dq,u}.
 	void Initialize(const Integer &n, const Integer &e, const Integer &d);
 
 	// PKCS8PrivateKey