Update documentation

cryptlib.h

@@ -2248,6 +2248,7 @@ public:
 	/// \sa SupportsPrecomputation(), Precompute()
 	virtual void LoadPrecomputation(BufferedTransformation &storedPrecomputation)
 		{CRYPTOPP_UNUSED(storedPrecomputation); CRYPTOPP_ASSERT(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation");}
+
 	/// \brief Save precomputation for later use
 	/// \param storedPrecomputation BufferedTransformation to write the precomputation
 	/// \throws NotImplemented

eprecomp.h

@@ -45,7 +45,7 @@ public:
 
 	/// \brief Decodes element in DER format
 	/// \param bt BufferedTransformation object
-	/// \param P Element to decode
+	/// \returns element in the group
 	virtual Element BERDecodeElement(BufferedTransformation &bt) const =0;
 
 	/// \brief Encodes element in DER format
@@ -64,14 +64,60 @@ public:
 
 	virtual ~DL_FixedBasePrecomputation() {}
 
+	/// \brief Determines whether this object is initialized
+	/// \returns true if this object is initialized, false otherwise
 	virtual bool IsInitialized() const =0;
+
+	/// \brief Set the base element
+	/// \param group the group
+	/// \param base element in the group
 	virtual void SetBase(const DL_GroupPrecomputation<Element> &group, const Element &base) =0;
+
+	/// \brief Get the base element
+	/// \param group the group
+	/// \returns base element in the group
 	virtual const Element & GetBase(const DL_GroupPrecomputation<Element> &group) const =0;
+
+	/// \brief Perform precomputation
+	/// \param group the group
+	/// \param maxExpBits used to calculate the exponent base
+	/// \param storage the suggested number of objects for the precompute table
+	/// \details The exact semantics of Precompute() varies, but it typically means calculate
+	///   a table of n objects that can be used later to speed up computation.
+	/// \details If a derived class does not override Precompute(), then the base class throws
+	///   NotImplemented.
+	/// \sa SupportsPrecomputation(), LoadPrecomputation(), SavePrecomputation()
 	virtual void Precompute(const DL_GroupPrecomputation<Element> &group, unsigned int maxExpBits, unsigned int storage) =0;
+
+	/// \brief Retrieve previously saved precomputation
+	/// \param group the the group
+	/// \param storedPrecomputation BufferedTransformation with the saved precomputation
+	/// \throws NotImplemented
+	/// \sa SupportsPrecomputation(), Precompute()
 	virtual void Load(const DL_GroupPrecomputation<Element> &group, BufferedTransformation &storedPrecomputation) =0;
+
+	/// \brief Save precomputation for later use
+	/// \param group the the group
+	/// \param storedPrecomputation BufferedTransformation to write the precomputation
+	/// \throws NotImplemented
+	/// \sa SupportsPrecomputation(), Precompute()
 	virtual void Save(const DL_GroupPrecomputation<Element> &group, BufferedTransformation &storedPrecomputation) const =0;
+
+	/// \brief Exponentiates an element
+	/// \param group the group
+	/// \param exponent the exponent
+	/// \return the result of the exponentiation
 	virtual Element Exponentiate(const DL_GroupPrecomputation<Element> &group, const Integer &exponent) const =0;
-	virtual Element CascadeExponentiate(const DL_GroupPrecomputation<Element> &group, const Integer &exponent, const DL_FixedBasePrecomputation<Element> &pc2, const Integer &exponent2) const =0;
+
+	/// \brief Exponentiates an element
+	/// \param pc1 the first the group precomputation
+	/// \param exponent1 the first exponent
+	/// \param pc2 the second the group precomputation
+	/// \param exponent2 the first exponent2
+	/// \returns the public element raised to the exponent
+	/// \details CascadeExponentiateBaseAndPublicElement raises the public element to
+	///   the base element and precomputation.
+	virtual Element CascadeExponentiate(const DL_GroupPrecomputation<Element> &pc1, const Integer &exponent1, const DL_FixedBasePrecomputation<Element> &pc2, const Integer &exponent2) const =0;
 };
 
 /// \brief DL_FixedBasePrecomputation adapter class
@@ -96,7 +142,7 @@ public:
 	void Load(const DL_GroupPrecomputation<Element> &group, BufferedTransformation &storedPrecomputation);
 	void Save(const DL_GroupPrecomputation<Element> &group, BufferedTransformation &storedPrecomputation) const;
 	Element Exponentiate(const DL_GroupPrecomputation<Element> &group, const Integer &exponent) const;
-	Element CascadeExponentiate(const DL_GroupPrecomputation<Element> &group, const Integer &exponent, const DL_FixedBasePrecomputation<Element> &pc2, const Integer &exponent2) const;
+	Element CascadeExponentiate(const DL_GroupPrecomputation<Element> &pc1, const Integer &exponent1, const DL_FixedBasePrecomputation<Element> &pc2, const Integer &exponent2) const;
 
 private:
 	void PrepareCascade(const DL_GroupPrecomputation<Element> &group, std::vector<BaseAndExponent<Element> > &eb, const Integer &exponent) const;

pubkey.h

@@ -786,19 +786,38 @@ public:
 			;
 	}
 
+	/// \brief Determines whether the object supports precomputation
+	/// \return true if the object supports precomputation, false otherwise
+	/// \sa Precompute()
 	bool SupportsPrecomputation() const {return true;}
 
+	/// \brief Perform precomputation
+	/// \param precomputationStorage the suggested number of objects for the precompute table
+	/// \throws NotImplemented
+	/// \details The exact semantics of Precompute() varies, but it typically means calculate
+	///   a table of n objects that can be used later to speed up computation.
+	/// \details If a derived class does not override Precompute(), then the base class throws
+	///   NotImplemented.
+	/// \sa SupportsPrecomputation(), LoadPrecomputation(), SavePrecomputation()
 	void Precompute(unsigned int precomputationStorage=16)
 	{
 		AccessBasePrecomputation().Precompute(GetGroupPrecomputation(), GetSubgroupOrder().BitCount(), precomputationStorage);
 	}
 
+	/// \brief Retrieve previously saved precomputation
+	/// \param storedPrecomputation BufferedTransformation with the saved precomputation
+	/// \throws NotImplemented
+	/// \sa SupportsPrecomputation(), Precompute()
 	void LoadPrecomputation(BufferedTransformation &storedPrecomputation)
 	{
 		AccessBasePrecomputation().Load(GetGroupPrecomputation(), storedPrecomputation);
 		m_validationLevel = 0;
 	}
 
+	/// \brief Save precomputation for later use
+	/// \param storedPrecomputation BufferedTransformation to write the precomputation
+	/// \throws NotImplemented
+	/// \sa SupportsPrecomputation(), Precompute()
 	void SavePrecomputation(BufferedTransformation &storedPrecomputation) const
 	{
 		GetBasePrecomputation().Save(GetGroupPrecomputation(), storedPrecomputation);
@@ -814,9 +833,9 @@ public:
 	/// \details The subgroup generator is set in the base precomputation
 	virtual void SetSubgroupGenerator(const Element &base) {AccessBasePrecomputation().SetBase(GetGroupPrecomputation(), base);}
 
-	/// \brief Retrieves the subgroup generator
+	/// \brief Exponentiates the base
-	/// \return the subgroup generator
+	/// \return the element after exponentiation
-	/// \details The subgroup generator is retrieved from the base precomputation.
+	/// \details ExponentiateBase() calls GetBasePrecomputation() and then exponentiates.
 	virtual Element ExponentiateBase(const Integer &exponent) const
 	{
 		return GetBasePrecomputation().Exponentiate(GetGroupPrecomputation(), exponent);

stdcpp.h

@@ -1,3 +1,8 @@
+// stdcpp.h - originally written and placed in the public domain by Wei Dai
+
+/// \file stdcpp.h
+/// \brief Common C++ header files
+
 #ifndef CRYPTOPP_STDCPP_H
 #define CRYPTOPP_STDCPP_H