Merge pull request #9458 from LinuxJedi/doc_fixes

Fix issues with the API documentation

Author: dgarske

doc/dox_comments/header_files/aes.h

@@ -1021,7 +1021,7 @@ int  wc_AesInit(Aes* aes, void* heap, int devId);
 
     \sa wc_AesInit
 */
-int  wc_AesFree(Aes* aes);
+void wc_AesFree(Aes* aes);
 
 /*!
     \ingroup AES
@@ -1203,19 +1203,19 @@ int wc_AesSivDecrypt(const byte* key, word32 keySz, const byte* assoc,
     \return other negative error values returned if AES or CMAC operations
     fail.
 
-    \param key buffer containing the key to use
-    \param keySz length of the key buffer in bytes
+    \param [in] key buffer containing the key to use
+    \param [in] keySz length of the key buffer in bytes
     \param[out] out buffer to hold the ciphertext. Should be the same length as
     the plaintext buffer
-    \param in plaintext buffer to encrypt
-    \param inSz length of plaintext buffer
-    \param nonce the cryptographic nonce to use for EAX operations
-    \param nonceSz length of nonce buffer in bytes
+    \param [in] in plaintext buffer to encrypt
+    \param [in] inSz length of plaintext buffer
+    \param [in] nonce the cryptographic nonce to use for EAX operations
+    \param [in] nonceSz length of nonce buffer in bytes
     \param[out] authTag pointer to the buffer in which to store the
     authentication tag
-    \param authTagSz length of the desired authentication tag
-    \param authIn pointer to the buffer containing input data to authenticate
-    \param authInSz length of the input authentication data
+    \param [in] authTagSz length of the desired authentication tag
+    \param [in] authIn pointer to the buffer containing input data to authenticate
+    \param [in] authInSz length of the input authentication data
 
     _Example_
     \code
@@ -1266,19 +1266,19 @@ WOLFSSL_API int  wc_AesEaxEncryptAuth(const byte* key, word32 keySz, byte* out,
     \return other negative error values returned if AES or CMAC operations
     fail.
 
-    \param key byte buffer containing the key to use
-    \param keySz length of the key buffer in bytes
+    \param [in] key byte buffer containing the key to use
+    \param [in] keySz length of the key buffer in bytes
     \param[out] out buffer to hold the plaintext. Should be the same length as
     the input ciphertext buffer
-    \param in ciphertext buffer to decrypt
-    \param inSz length of ciphertext buffer
-    \param nonce the cryptographic nonce to use for EAX operations
-    \param nonceSz length of nonce buffer in bytes
-    \param authTag buffer that holds the authentication tag to check the
+    \param [in] in ciphertext buffer to decrypt
+    \param [in] inSz length of ciphertext buffer
+    \param [in] nonce the cryptographic nonce to use for EAX operations
+    \param [in] nonceSz length of nonce buffer in bytes
+    \param [in] authTag buffer that holds the authentication tag to check the
     authenticity of the data against
-    \param authTagSz Length of the input authentication tag
-    \param authIn pointer to the buffer containing input data to authenticate
-    \param authInSz length of the input authentication data
+    \param [in] authTagSz Length of the input authentication tag
+    \param [in] authIn pointer to the buffer containing input data to authenticate
+    \param [in] authInSz length of the input authentication data
 
     _Example_
     \code
@@ -1390,13 +1390,13 @@ WOLFSSL_API int  wc_AesEaxInit(AesEax* eax,
     \return 0 on success
     \return error code on failure
 
-    \param eax AES EAX structure holding the context of the AEAD operation
+    \param [in] eax AES EAX structure holding the context of the AEAD operation
     \param[out] out output buffer holding the ciphertext
-    \param in input buffer holding the plaintext to encrypt
-    \param inSz size in bytes of the input data buffer
-    \param authIn (optional) input data to add to the authentication stream
+    \param [in] in input buffer holding the plaintext to encrypt
+    \param [in] inSz size in bytes of the input data buffer
+    \param [in] authIn (optional) input data to add to the authentication stream
     This argument should be NULL if not used
-    \param authInSz size in bytes of the input authentication data
+    \param [in] authInSz size in bytes of the input authentication data
 
     _Example_
     \code
@@ -1455,13 +1455,13 @@ WOLFSSL_API int  wc_AesEaxEncryptUpdate(AesEax* eax, byte* out,
     \return 0 on success
     \return error code on failure
 
-    \param eax AES EAX structure holding the context of the AEAD operation
+    \param [in] eax AES EAX structure holding the context of the AEAD operation
     \param[out] out output buffer holding the decrypted plaintext
-    \param in input buffer holding the ciphertext
-    \param inSz size in bytes of the input data buffer
-    \param authIn (optional) input data to add to the authentication stream
+    \param [in] in input buffer holding the ciphertext
+    \param [in] inSz size in bytes of the input data buffer
+    \param [in] authIn (optional) input data to add to the authentication stream
     This argument should be NULL if not used
-    \param authInSz size in bytes of the input authentication data
+    \param [in] authInSz size in bytes of the input authentication data
 
 
     _Example_
@@ -1742,13 +1742,13 @@ WOLFSSL_API int wc_AesEaxFree(AesEax* eax);
     \return BAD_FUNC_ARG if input arguments are invalid.
     \return other negative error codes for encryption failures.
 
-    \param key pointer to the AES key used for encryption.
-    \param keySz size of the AES key in bytes (16, 24, or 32 bytes).
+    \param [in] key pointer to the AES key used for encryption.
+    \param [in] keySz size of the AES key in bytes (16, 24, or 32 bytes).
     \param[out] out buffer to hold the encrypted ciphertext. Must be at least
     the size of the input.
-    \param in pointer to the plaintext input data to encrypt.
-    \param inSz size of the plaintext input data in bytes.
-    \param iv pointer to the initialization vector (IV) used for encryption.
+    \param [in] in pointer to the plaintext input data to encrypt.
+    \param [in] inSz size of the plaintext input data in bytes.
+    \param [in] iv pointer to the initialization vector (IV) used for encryption.
     Must be 16 bytes.
 
     _Example_
@@ -1780,13 +1780,13 @@ int wc_AesCtsEncrypt(const byte* key, word32 keySz, byte* out,
     \return BAD_FUNC_ARG if input arguments are invalid.
     \return other negative error codes for encryption failures.
 
-    \param key pointer to the AES key used for encryption.
-    \param keySz size of the AES key in bytes (16, 24, or 32 bytes).
+    \param [in] key pointer to the AES key used for encryption.
+    \param [in] keySz size of the AES key in bytes (16, 24, or 32 bytes).
     \param[out] out buffer to hold the encrypted ciphertext. Must be at least
                  the same size as the input plaintext.
-    \param in pointer to the plaintext input data to encrypt.
-    \param inSz size of the plaintext input data in bytes.
-    \param iv pointer to the initialization vector (IV) used for encryption.
+    \param [in] in pointer to the plaintext input data to encrypt.
+    \param [in] inSz size of the plaintext input data in bytes.
+    \param [in] iv pointer to the initialization vector (IV) used for encryption.
              Must be 16 bytes.
     _Example_
     \code
@@ -1813,13 +1813,13 @@ int wc_AesCtsEncrypt(const byte* key, word32 keySz, byte* out,
     \return 0 on successful decryption.
     \return BAD_FUNC_ARG if input arguments are invalid.
     \return other negative error codes for decryption failures.
-    \param key pointer to the AES key used for decryption.
-    \param keySz size of the AES key in bytes (16, 24, or 32 bytes).
+    \param [in] key pointer to the AES key used for decryption.
+    \param [in] keySz size of the AES key in bytes (16, 24, or 32 bytes).
     \param[out] out buffer to hold the decrypted plaintext. Must be at least
                  the same size as the input ciphertext.
-    \param in pointer to the ciphertext input data to decrypt.
-    \param inSz size of the ciphertext input data in bytes.
-    \param iv pointer to the initialization vector (IV) used for decryption.
+    \param [in] in pointer to the ciphertext input data to decrypt.
+    \param [in] inSz size of the ciphertext input data in bytes.
+    \param [in] iv pointer to the initialization vector (IV) used for decryption.
              Must be 16 bytes.
     _Example_
     \code
@@ -1845,14 +1845,14 @@ int wc_AesCtsDecrypt(const byte* key, word32 keySz, byte* out,
            It processes a chunk of plaintext and stores intermediate data.
     \return 0 on successful processing.
     \return BAD_FUNC_ARG if input arguments are invalid.
-    \param aes pointer to the Aes structure holding the context of the operation.
+    \param [in] aes pointer to the Aes structure holding the context of the operation.
     \param[out] out buffer to hold the encrypted ciphertext. Must be large enough
                  to store the output from this update step.
     \param[out] outSz size in bytes of the output data written to the \c out buffer.
-                     On input, it should contain the maximum number of bytes that can
-                     be written to the \c out buffer.
-    \param in pointer to the plaintext input data to encrypt.
-    \param inSz size of the plaintext input data in bytes.
+                    On input, it should contain the maximum number of bytes that can
+                    be written to the \c out buffer.
+    \param [in] in pointer to the plaintext input data to encrypt.
+    \param [in] inSz size of the plaintext input data in bytes.
     _Example_
     \code
         Aes aes;
@@ -1880,7 +1880,7 @@ int wc_AesCtsEncryptUpdate(Aes* aes, byte* out, word32* outSz,
            It processes any remaining plaintext and completes the encryption.
     \return 0 on successful encryption completion.
     \return BAD_FUNC_ARG if input arguments are invalid.
-    \param aes pointer to the Aes structure holding the context of the operation.
+    \param [in] aes pointer to the Aes structure holding the context of the operation.
     \param[out] out buffer to hold the final encrypted ciphertext. Must be large
                  enough to store any remaining ciphertext from this final step.
     \param[out] outSz size in bytes of the output data written to the \c out buffer.
@@ -1913,14 +1913,14 @@ int wc_AesCtsEncryptFinal(Aes* aes, byte* out, word32* outSz);
            It processes a chunk of ciphertext and stores intermediate data.
     \return 0 on successful processing.
     \return BAD_FUNC_ARG if input arguments are invalid.
-    \param aes pointer to the Aes structure holding the context of the operation.
+    \param [in] aes pointer to the Aes structure holding the context of the operation.
     \param[out] out buffer to hold the decrypted plaintext. Must be large enough
                  to store the output from this update step.
     \param[out] outSz size in bytes of the output data written to the \c out buffer.
                      On input, it should contain the maximum number of bytes that can
                      be written to the \c out buffer.
-    \param in pointer to the ciphertext input data to decrypt.
-    \param inSz size of the ciphertext input data in bytes.
+    \param [in] in pointer to the ciphertext input data to decrypt.
+    \param [in] inSz size of the ciphertext input data in bytes.
     _Example_
     \code
         Aes aes;
@@ -1948,7 +1948,7 @@ int wc_AesCtsDecryptUpdate(Aes* aes, byte* out, word32* outSz,
            It processes any remaining ciphertext and completes the decryption.
     \return 0 on successful decryption completion.
     \return BAD_FUNC_ARG if input arguments are invalid.
-    \param aes pointer to the Aes structure holding the context of the operation.
+    \param [in] aes pointer to the Aes structure holding the context of the operation.
     \param[out] out buffer to hold the final decrypted plaintext. Must be large
                  enough to store any remaining plaintext from this final step.
     \param[out] outSz size in bytes of the output data written to the \c out buffer.

doc/dox_comments/header_files/asn_public.h

@@ -19,7 +19,7 @@
     \sa wc_MakeCert
     \sa wc_MakeCertReq
 */
-int wc_InitCert(Cert*);
+int wc_InitCert(Cert* cert);
 
 /*!
      \ingroup ASN
@@ -2524,4 +2524,3 @@ int wc_Asn1_SetFile(Asn1* asn1, XFILE file);
  */
 int wc_Asn1_PrintAll(Asn1* asn1, Asn1PrintOptions* opts, unsigned char* data,
     word32 len);
-

doc/dox_comments/header_files/camellia.h

@@ -35,8 +35,8 @@
     \sa wc_CamelliaCbcEncrypt
     \sa wc_CamelliaCbcDecrypt
 */
-int  wc_CamelliaSetKey(Camellia* cam,
-                                   const byte* key, word32 len, const byte* iv);
+int  wc_CamelliaSetKey(wc_Camellia* cam, const byte* key, word32 len,
+                                   const byte* iv);
 
 /*!
     \ingroup Camellia
@@ -64,7 +64,7 @@ int  wc_CamelliaSetKey(Camellia* cam,
 
     \sa wc_CamelliaSetKey
 */
-int  wc_CamelliaSetIV(Camellia* cam, const byte* iv);
+int  wc_CamelliaSetIV(wc_Camellia* cam, const byte* iv);
 
 /*!
     \ingroup Camellia
@@ -92,7 +92,7 @@ int  wc_CamelliaSetIV(Camellia* cam, const byte* iv);
 
     \sa wc_CamelliaDecryptDirect
 */
-int  wc_CamelliaEncryptDirect(Camellia* cam, byte* out,
+int  wc_CamelliaEncryptDirect(wc_Camellia* cam, byte* out,
                                                                 const byte* in);
 
 /*!
@@ -122,7 +122,7 @@ int  wc_CamelliaEncryptDirect(Camellia* cam, byte* out,
 
     \sa wc_CamelliaEncryptDirect
 */
-int  wc_CamelliaDecryptDirect(Camellia* cam, byte* out,
+int  wc_CamelliaDecryptDirect(wc_Camellia* cam, byte* out,
                                                                 const byte* in);
 
 /*!
@@ -151,7 +151,7 @@ int  wc_CamelliaDecryptDirect(Camellia* cam, byte* out,
 
     \sa wc_CamelliaCbcDecrypt
 */
-int wc_CamelliaCbcEncrypt(Camellia* cam,
+int wc_CamelliaCbcEncrypt(wc_Camellia* cam,
                                           byte* out, const byte* in, word32 sz);
 
 /*!
@@ -180,5 +180,5 @@ int wc_CamelliaCbcEncrypt(Camellia* cam,
 
     \sa wc_CamelliaCbcEncrypt
 */
-int wc_CamelliaCbcDecrypt(Camellia* cam,
+int wc_CamelliaCbcDecrypt(wc_Camellia* cam,
                                           byte* out, const byte* in, word32 sz);

doc/dox_comments/header_files/chacha20_poly1305.h

@@ -50,8 +50,8 @@
 int wc_ChaCha20Poly1305_Encrypt(
                 const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE],
                 const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE],
-                const byte* inAAD, const word32 inAADLen,
-                const byte* inPlaintext, const word32 inPlaintextLen,
+                const byte* inAAD, word32 inAADLen,
+                const byte* inPlaintext, word32 inPlaintextLen,
                 byte* outCiphertext,
                 byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]);
 
@@ -118,7 +118,7 @@ int wc_ChaCha20Poly1305_Encrypt(
 int wc_ChaCha20Poly1305_Decrypt(
                 const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE],
                 const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE],
-                const byte* inAAD, const word32 inAADLen,
-                const byte* inCiphertext, const word32 inCiphertextLen,
+                const byte* inAAD, word32 inAADLen,
+                const byte* inCiphertext, word32 inCiphertextLen,
                 const byte inAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE],
                 byte* outPlaintext);

doc/dox_comments/header_files/curve25519.h

@@ -108,7 +108,7 @@ int wc_curve25519_shared_secret(curve25519_key* private_key,
     the received public key.
     \param [out] out Pointer to a buffer in which to store the 32 byte computed
     secret key.
-    \param pin,out] outlen Pointer in which to store the length written to the
+    \param [in,out] outlen Pointer in which to store the length written to the
     output buffer.
     \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
     form to use.
@@ -537,7 +537,7 @@ int wc_curve25519_import_public_ex(const byte* in, word32 inLen,
     \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
 
     \param [in] pub Pointer to the buffer containing the public key to check.
-    \param [in] pubLen Length of the public key to check.
+    \param [in] pubSz Length of the public key to check.
     \param [in] endian EC25519_BIG_ENDIAN or EC25519_LITTLE_ENDIAN to set which
     form to use.
 

doc/dox_comments/header_files/curve448.h

@@ -533,7 +533,7 @@ int wc_curve448_import_public_ex(const byte* in, word32 inLen,
     \return BAD_FUNC_ARG Returned if any of the input parameters are NULL.
 
     \param [in] pub Pointer to the buffer containing the public key to check.
-    \param [in] pubLen Length of the public key to check.
+    \param [in] pubSz Length of the public key to check.
     \param [in] endian EC448_BIG_ENDIAN or EC448_LITTLE_ENDIAN to set which
     form to use.
 

doc/dox_comments/header_files/dh.h

@@ -40,7 +40,7 @@ int wc_InitDhKey(DhKey* key);
 
     \sa wc_InitDhKey
 */
-void wc_FreeDhKey(DhKey* key);
+int wc_FreeDhKey(DhKey* key);
 
 /*!
     \ingroup Diffie-Hellman
@@ -185,7 +185,7 @@ int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz,
     \sa wc_DhSetKey
 */
 int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
-                           word32);
+                           word32 inSz);
 
 /*!
     \ingroup Diffie-Hellman
@@ -396,5 +396,5 @@ int wc_DhSetKey_ex(DhKey* key, const byte* p, word32 pSz,
 
 /*!
     \ingroup Diffie-Hellman
-*/
+ */
 int wc_FreeDhKey(DhKey* key);