From 3cb86675af234ad8d5f95ec7eeeae0b7e72f2929 Mon Sep 17 00:00:00 2001
From: Jeffrey Walton <noloader@gmail.com>
Date: Mon, 28 Jan 2019 06:13:43 -0500
Subject: [PATCH] Update documentation

---
 cryptlib.h | 44 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 38 insertions(+), 6 deletions(-)

diff --git a/cryptlib.h b/cryptlib.h
index c5cbce13..76012686 100644
--- a/cryptlib.h
+++ b/cryptlib.h
@@ -1301,30 +1301,62 @@ public:
 	/// \brief Provides the maximum length of AAD that can be input
 	/// \return the maximum length of AAD that can be input before the encrypted data
 	virtual lword MaxHeaderLength() const =0;
+
 	/// \brief Provides the maximum length of encrypted data
 	/// \return the maximum length of encrypted data
 	virtual lword MaxMessageLength() const =0;
+
 	/// \brief Provides the the maximum length of AAD
 	/// \return the maximum length of AAD that can be input after the encrypted data
 	virtual lword MaxFooterLength() const {return 0;}
+
 	/// \brief Determines if data lengths must be specified prior to inputting data
 	/// \return true if the data lengths are required before inputting data, false otherwise
 	/// \details if this function returns true, SpecifyDataLengths() must be called before attempting to input data.
 	///   This is the case for some schemes, such as CCM.
 	/// \sa SpecifyDataLengths()
 	virtual bool NeedsPrespecifiedDataLengths() const {return false;}
-	/// \brief Prespecifies the data lengths
-	/// \details this function only needs to be called if NeedsPrespecifiedDataLengths() returns true
+
+	/// \brief Prescribes the data lengths
+	/// \param headerLength size of data before message is input, in bytes
+	/// \param messageLength size of the message, in bytes
+	/// \param footerLength size of data after message is input, in bytes
+	/// \details SpecifyDataLengths() only needs to be called if NeedsPrespecifiedDataLengths() returns <tt>true</tt>.
+	///   If <tt>true</tt>, then <tt>headerLength</tt> will be validated against <tt>MaxHeaderLength()</tt>,
+	///   <tt>messageLength</tt> will be validated against <tt>MaxMessageLength()</tt>, and
+	///   <tt>footerLength</tt> will be validated against <tt>MaxFooterLength()</tt>.
 	/// \sa NeedsPrespecifiedDataLengths()
 	void SpecifyDataLengths(lword headerLength, lword messageLength, lword footerLength=0);
+
 	/// \brief Encrypts and calculates a MAC in one call
-	/// \details EncryptAndAuthenticate() encrypts and generates the MAC in one call. The function will truncate MAC if
-	///   <tt>macSize < TagSize()</tt>.
+	/// \param ciphertext the encryption buffer
+	/// \param mac the mac buffer
+	/// \param macLength the size of the MAC buffer, in bytes
+	/// \param iv the iv buffer
+	/// \param ivLength the size of the IV buffer, in bytes
+	/// \param header the AAD buffer
+	/// \param headerLength the size of the AAD buffer, in bytes
+	/// \param message the message buffer
+	/// \param messageLength the size of the messagetext buffer, in bytes
+	/// \details EncryptAndAuthenticate() encrypts and generates the MAC in one call. The function
+	///   truncates the MAC if <tt>macSize < TagSize()</tt>.
 	virtual void EncryptAndAuthenticate(byte *ciphertext, byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *header, size_t headerLength, const byte *message, size_t messageLength);
+
 	/// \brief Decrypts and verifies a MAC in one call
+	/// \param message the decryption buffer
+	/// \param mac the mac buffer
+	/// \param macLength the size of the MAC buffer, in bytes
+	/// \param iv the iv buffer
+	/// \param ivLength the size of the IV buffer, in bytes
+	/// \param header the AAD buffer
+	/// \param headerLength the size of the AAD buffer, in bytes
+	/// \param cipher the cipher buffer
+	/// \param cipherLength the size of the ciphertext buffer, in bytes
 	/// \return true if the MAC is valid and the decoding succeeded, false otherwise
-	/// \details DecryptAndVerify() decrypts and verifies the MAC in one call. The function returns true iff MAC is valid.
-	///   DecryptAndVerify() will assume MAC is truncated if <tt>macLength < TagSize()</tt>.
+	/// \details DecryptAndVerify() decrypts and verifies the MAC in one call.
+	/// <tt>message</tt> is a decryption buffer and should be at least as large as the ciphertext buffer.
+	/// \details The function returns true iff MAC is valid. DecryptAndVerify() assumes the MAC
+	///  is truncated if <tt>macLength < TagSize()</tt>.
 	virtual bool DecryptAndVerify(byte *message, const byte *mac, size_t macLength, const byte *iv, int ivLength, const byte *header, size_t headerLength, const byte *ciphertext, size_t ciphertextLength);
 
 	/// \brief Provides the name of this algorithm