Documentation Fixes (#1520)

* Fixed documentation errors found by check_api script
* Formatting changes so that comments/API pairs are more obvious

doc/dox_comments/header_files/asn_public.h

@@ -20,6 +20,7 @@
     \sa wc_MakeCertReq
 */
 WOLFSSL_API int wc_InitCert(Cert*);
+
 /*!
     \ingroup ASN
     
@@ -65,6 +66,7 @@ WOLFSSL_API int wc_InitCert(Cert*);
 */
 WOLFSSL_API int  wc_MakeCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
                              ecc_key*, WC_RNG*);
+                             
 /*!
     \ingroup ASN
     
@@ -111,6 +113,7 @@ WOLFSSL_API int  wc_MakeCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
 */
 WOLFSSL_API int  wc_MakeCertReq(Cert*, byte* derBuffer, word32 derSz,
                                     RsaKey*, ecc_key*);
+                                    
 /*!
     \ingroup ASN
     
@@ -163,6 +166,7 @@ WOLFSSL_API int  wc_MakeCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
 */
 WOLFSSL_API int  wc_SignCert(int requestSz, int sigType, byte* derBuffer,
                              word32 derSz, RsaKey*, ecc_key*, WC_RNG*);
+                             
 /*!
     \ingroup ASN
     
@@ -208,6 +212,7 @@ WOLFSSL_API int  wc_SignCert(int requestSz, int sigType, byte* derBuffer,
 */
 WOLFSSL_API int  wc_MakeSelfCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
                              WC_RNG*);
+                             
 /*!
     \ingroup ASN
     
@@ -270,6 +275,7 @@ WOLFSSL_API int  wc_MakeSelfCert(Cert*, byte* derBuffer, word32 derSz, RsaKey*,
     \sa wc_SetIssuerBuffer
 */
 WOLFSSL_API int  wc_SetIssuer(Cert*, const char*);
+
 /*!
     \ingroup ASN
     
@@ -328,6 +334,7 @@ WOLFSSL_API int  wc_SetIssuer(Cert*, const char*);
     \sa wc_SetIssuer
 */
 WOLFSSL_API int  wc_SetSubject(Cert*, const char*);
+
 /*!
     \ingroup ASN
     
@@ -388,6 +395,7 @@ WOLFSSL_API int  wc_SetSubject(Cert*, const char*);
     \sa wc_SetIssuer
 */
 WOLFSSL_API int  wc_SetAltNames(Cert*, const char*);
+
 /*!
     \ingroup ASN
     
@@ -453,6 +461,7 @@ WOLFSSL_API int  wc_SetSubject(Cert*, const char*);
     \sa wc_SetIssuer
 */
 WOLFSSL_API int  wc_SetIssuerBuffer(Cert*, const byte*, int);
+
 /*!
     \ingroup ASN
     
@@ -517,6 +526,7 @@ WOLFSSL_API int  wc_SetIssuerBuffer(Cert*, const byte*, int);
     \sa wc_SetSubject
 */
 WOLFSSL_API int  wc_SetSubjectBuffer(Cert*, const byte*, int);
+
 /*!
     \ingroup ASN
     
@@ -584,6 +594,7 @@ WOLFSSL_API int  wc_SetSubjectBuffer(Cert*, const byte*, int);
     \sa wc_SetAltNames
 */
 WOLFSSL_API int  wc_SetAltNamesBuffer(Cert*, const byte*, int);
+
 /*!
     \ingroup ASN
     
@@ -648,6 +659,7 @@ WOLFSSL_API int  wc_SetAltNamesBuffer(Cert*, const byte*, int);
     \sa wc_InitCert
 */
 WOLFSSL_API int  wc_SetDatesBuffer(Cert*, const byte*, int);
+
 /*!
     \ingroup ASN
     
@@ -711,6 +723,7 @@ WOLFSSL_API int wc_SetAuthKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
     \sa wc_SetAuthKeyId
 */
 WOLFSSL_API int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz);
+
 /*!
     \ingroup ASN
     
@@ -739,6 +752,7 @@ WOLFSSL_API int wc_SetAuthKeyIdFromCert(Cert *cert, const byte *der, int derSz);
     \sa wc_SetAuthKeyIdFromCert
 */
 WOLFSSL_API int wc_SetAuthKeyId(Cert *cert, const char* file);
+
 /*!
     \ingroup ASN
     
@@ -771,6 +785,7 @@ WOLFSSL_API int wc_SetAuthKeyId(Cert *cert, const char* file);
 */
 WOLFSSL_API int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
                                                 ecc_key *eckey);
+                                                
 /*!
     \ingroup ASN
     
@@ -801,6 +816,7 @@ WOLFSSL_API int wc_SetSubjectKeyIdFromPublicKey(Cert *cert, RsaKey *rsakey,
     \sa wc_SetSubjectKeyIdFromPublicKey
 */
 WOLFSSL_API int wc_SetSubjectKeyId(Cert *cert, const char* file);
+
 /*!
     \ingroup ASN
     
@@ -833,6 +849,7 @@ WOLFSSL_API int wc_SetSubjectKeyId(Cert *cert, const char* file);
 */
 WOLFSSL_API int wc_SetSubjectKeyIdFromNtruPublicKey(Cert *cert, byte *ntruKey,
                                                     word16 ntruKeySz);
+                                                    
 /*!
     \ingroup RSA
     
@@ -866,6 +883,7 @@ WOLFSSL_API int wc_SetSubjectKeyIdFromNtruPublicKey(Cert *cert, byte *ntruKey,
     \sa wc_MakeRsaKey
 */
 WOLFSSL_API int wc_SetKeyUsage(Cert *cert, const char *value);
+
 /*!
     \ingroup ASN
     
@@ -916,6 +934,7 @@ WOLFSSL_API int wc_SetKeyUsage(Cert *cert, const char *value);
 WOLFSSL_API int  wc_MakeNtruCert(Cert*, byte* derBuffer, word32 derSz,
                              const byte* ntruKey, word16 keySz,
                              WC_RNG*);
+                             
 /*!
     \ingroup ASN
     
@@ -946,6 +965,7 @@ WOLFSSL_API int  wc_MakeNtruCert(Cert*, byte* derBuffer, word32 derSz,
 */
 WOLFSSL_API int wc_PemPubKeyToDer(const char* fileName,
                                        unsigned char* derBuf, int derSz);
+                                       
 /*!
     \ingroup ASN
     
@@ -1055,6 +1075,7 @@ int wc_PemCertToDer(const char* fileName,unsigned char* derBuf,int derSz);
 */
 WOLFSSL_API int wc_DerToPem(const byte* der, word32 derSz, byte* output,
                                 word32 outputSz, int type);
+                                
 /*!
     \ingroup ASN
     
@@ -1137,6 +1158,7 @@ int wc_PemCertToDer(const char* fileName,unsigned char* derBuf,int derSz);
 */
 WOLFSSL_API int wc_KeyPemToDer(const unsigned char*, int,
                                     unsigned char*, int, const char*);
+                                    
 /*!
     \ingroup CertsKeys
 
@@ -1168,34 +1190,6 @@ WOLFSSL_API int wc_KeyPemToDer(const unsigned char*, int,
 */
 WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
                                      unsigned char*, int, int);
-/*!
-    \ingroup CertsKeys
-
-    \brief Converts the PEM format to DER format.
-    
-    \return int an int type representing the bytes written to buffer.
-    \param <0 returned for an error.
-    \param BAD_FUNC_ARG returned if the DER length is incorrect or if the 
-    pem buff, or buffSz arguments are NULL.
-    
-    _Example_
-    \code
-    unsigned char* pem = “pem file”;
-    int pemSz = sizeof(pem)/sizeof(char);
-    unsigned char* buff;
-    int buffSz;
-    ...
-    if(wc_PubKeyPemToDer(pem, pemSz, buff, buffSz)!= SSL_SUCCESS){
-        // Conversion was not successful
-    }
-    \endcode
-    
-    \sa wc_PubKeyPemToDer
-    \sa wc_PemPubKeyToDer
-    \sa wc_PemToDer
-*/
-        WOLFSSL_API int wc_PubKeyPemToDer(const unsigned char*, int,
-                                               unsigned char*, int);
                                      
 /*!
     \ingroup ASN
@@ -1246,7 +1240,7 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
     // read key into tmp buffer
 
     wc_ecc_init(&key); // initialize key
-    ret = wc_Ecc_PrivateKeyDecode(tmp, &idx, &key, (word32)inSz);
+    ret = wc_EccPrivateKeyDecode(tmp, &idx, &key, (word32)inSz);
     if(ret < 0) {
         // error decoding ecc key
     }
@@ -1256,6 +1250,7 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
 */
 WOLFSSL_API int wc_EccPrivateKeyDecode(const byte*, word32*,
                                            ecc_key*, word32);
+                                           
 /*!
     \ingroup ASN
     
@@ -1299,6 +1294,7 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
     \sa wc_RsaKeyToDer
 */
 WOLFSSL_API int wc_EccKeyToDer(ecc_key*, byte* output, word32 inLen);
+
 /*!
     \ingroup ASN
     
@@ -1333,6 +1329,7 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
 */
 WOLFSSL_API int wc_EccPublicKeyDecode(const byte*, word32*,
                                               ecc_key*, word32);
+                                              
 /*!
     \ingroup ASN
     
@@ -1373,6 +1370,7 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
 */
 WOLFSSL_API int wc_EccPublicKeyToDer(ecc_key*, byte* output,
                                          word32 inLen, int with_AlgCurve);
+                                         
 /*!
     \ingroup ASN
     
@@ -1408,6 +1406,7 @@ WOLFSSL_API int wc_CertPemToDer(const unsigned char*, int,
 */
 WOLFSSL_API word32 wc_EncodeSignature(byte* out, const byte* digest,
                                       word32 digSz, int hashOID);
+                                      
 /*!
     \ingroup ASN
     

doc/dox_comments/header_files/blake2.h

@@ -81,7 +81,7 @@ WOLFSSL_API int wc_Blake2bUpdate(Blake2b*, const byte*, word32);
     wc_InitBlake2b(&b2b, 64); 
     ... // call wc_Blake2bUpdate to add data to hash
 
-    ret = 2c_Blake2bFinal(&b2b, hash, 64);
+    ret = wc_Blake2bFinal(&b2b, hash, 64);
     if( ret != 0) {
     	// error generating blake2b hash
     }

doc/dox_comments/header_files/camellia.h

@@ -85,7 +85,7 @@ WOLFSSL_API int  wc_CamelliaSetIV(Camellia* cam, const byte* iv);
     byte plain[] = { // initialize with message to encrypt };
     byte cipher[16];
     
-    wc_CamelliaEncrypt(&ca, cipher, plain);
+    wc_CamelliaEncryptDirect(&ca, cipher, plain);
     \endcode
     
     \sa wc_CamelliaDecryptDirect

doc/dox_comments/header_files/ecc.h

@@ -86,7 +86,7 @@ int wc_ecc_make_key(WC_RNG* rng, int keysize, ecc_key* key);
     \sa wc_ecc_point_is_at_infinity
 */
 WOLFSSL_API
-int wc_ecc_make_pub(ecc_key* key, ecc_point* pubOut);
+int wc_ecc_check_key(ecc_key* key);
 
 /*!
     \ingroup ECC
@@ -195,7 +195,7 @@ int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out,
 
     point = wc_ecc_new_point();
 
-    result = wc_ecc_shared_secret_ssh(&key, point, 
+    result = wc_ecc_shared_secret_ex(&key, point, 
     &shared_secret, &secret_size);
 
     if (result != MP_OKAY)
@@ -1334,7 +1334,7 @@ int wc_ecc_size(ecc_key* key);
     
     _Example_
     \code
-    int sigSz = wc_ecc_sig_size(32);
+    int sigSz = wc_ecc_sig_size_calc(32);
     if ( sigSz == 0) {
     	// error determining sig size
     }

doc/dox_comments/header_files/evp.h

@@ -36,7 +36,7 @@ WOLFSSL_API const WOLFSSL_EVP_CIPHER* wolfSSL_EVP_des_ede3_ecb(void);
     _Example_
     \code
     WOLFSSL_EVP_CIPHER* cipher;
-    cipher = wolfSSL_EVP_des_ecb();
+    cipher = wolfSSL_EVP_des_cbc();
     …
     \endcode
     

doc/dox_comments/header_files/pkcs7.h

@@ -111,7 +111,7 @@ WOLFSSL_API void wc_PKCS7_Free(PKCS7* pkcs7);
     pkcs7.contentSz = dataSz;
     ... etc.
 
-    ret = wc_PKCS7_EnocodeData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
+    ret = wc_PKCS7_EncodeData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
     if ( ret != 0 ) {
 	    // error encoding into output buffer
     }
@@ -182,7 +182,7 @@ WOLFSSL_API int  wc_PKCS7_EncodeData(PKCS7* pkcs7, byte* output,
     pkcs7.contentSz = dataSz;
     ... etc.
 
-    ret = wc_PKCS7_EnocodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
+    ret = wc_PKCS7_EncodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
     if ( ret != 0 ) {
     	// error encoding into output buffer
     }
@@ -258,7 +258,7 @@ WOLFSSL_API int  wc_PKCS7_EncodeSignedData(PKCS7* pkcs7,
     pkcs7.contentSz = dataSz;
     ... etc.
 
-    ret = wc_PKCS7_EnocodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
+    ret = wc_PKCS7_EncodeSignedData(&pkcs7, pkcs7Buff, sizeof(pkcs7Buff));
     if ( ret != 0 ) {
     	// error encoding into output buffer
     }

doc/dox_comments/header_files/rsa.h

@@ -18,7 +18,7 @@
     \code
     RsaKey enc;
     int ret;
-    ret = wc_RsaInitKey(&enc, NULL); // not using heap hint. No custom memory
+    ret = wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
     if ( ret != 0 ) {
     	// error initializing RSA key
     }

doc/dox_comments/header_files/sha256.h

@@ -227,8 +227,8 @@ WOLFSSL_API int wc_Sha224Update(wc_Sha224*, const byte*, word32);
         WOLFSSL_MSG("wc_InitSha224 failed");
     }
     else {
-        wc_Sha256Update(&sha224, data, len);
+        wc_Sha224Update(&sha224, data, len);
-        wc_Sha256Final(&sha224, hash);
+        wc_Sha224Final(&sha224, hash);
     }
     \endcode
     

doc/dox_comments/header_files/ssl.h

@@ -2179,7 +2179,7 @@ WOLFSSL_API int  wolfSSL_get_alert_history(WOLFSSL*, WOLFSSL_ALERT_HISTORY *);
     
     \sa wolfSSL_get_session
 */
-WOLFSSL_API int        wolfSSL_set_session(WOLFSSL* ssl,WOLFSSL_SESSION* session);
+WOLFSSL_API int        wolfSSL_set_session(WOLFSSL*, WOLFSSL_SESSION*);
 /*!
     \ingroup IO
 
@@ -2217,7 +2217,7 @@ WOLFSSL_API int        wolfSSL_set_session(WOLFSSL* ssl,WOLFSSL_SESSION* session
     
     \sa wolfSSL_set_session
 */
-WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL* ssl);
+WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL*);
 /*!
     \ingroup IO
 
@@ -2244,7 +2244,7 @@ WOLFSSL_API WOLFSSL_SESSION* wolfSSL_get_session(WOLFSSL* ssl);
     \sa wolfSSL_get_session
     \sa wolfSSL_set_session
 */
-WOLFSSL_API void       wolfSSL_flush_sessions(WOLFSSL_CTX *ctx, long tm);
+WOLFSSL_API void       wolfSSL_flush_sessions(WOLFSSL_CTX*, long);
 /*!
     \ingroup TLS
 
@@ -2279,7 +2279,7 @@ WOLFSSL_API void       wolfSSL_flush_sessions(WOLFSSL_CTX *ctx, long tm);
     
     \sa GetSessionClient
 */
-WOLFSSL_API int        wolfSSL_SetServerID(WOLFSSL* ssl, const unsigned char*,
+WOLFSSL_API int        wolfSSL_SetServerID(WOLFSSL*, const unsigned char*,
                                          int, int);
 /*!
     \ingroup IO

doc/dox_comments/header_files/wolfio.h

@@ -295,7 +295,7 @@ WOLFSSL_API void wolfSSL_SetIOReadCtx( WOLFSSL* ssl, void *ctx);
     WOLFSSL* ssl = 0;
     ...
     // Manually setting the socket fd as the send CTX, for example
-    wolfSSL_SetIOSendCtx(ssl, &sockfd);
+    wolfSSL_SetIOWriteCtx(ssl, &sockfd);
     ...
     \endcode
     
@@ -427,7 +427,7 @@ WOLFSSL_API void wolfSSL_SetIOReadFlags( WOLFSSL* ssl, int flags);
     WOLFSSL* ssl = 0;
     ...
     // Manually setting send flags to 0
-    wolfSSL_SetIOSendFlags(ssl, 0);
+    wolfSSL_SetIOWriteFlags(ssl, 0);
     ...
     \endcode