diff --git a/doc/README_DOXYGEN b/doc/README_DOXYGEN index a7614b8d5..4fad8ca40 100644 --- a/doc/README_DOXYGEN +++ b/doc/README_DOXYGEN @@ -24,7 +24,7 @@ texlive-pictures [installed,automatic] ---- Generating the Documentation ---- If you are looking to just generate the html documentation and not interested in -how to add your own just run one of the following comands from the main wolfssl +how to add your own just run one of the following commands from the main wolfssl directory: make dox (this option will make both html and pdf documentation) @@ -153,7 +153,7 @@ The general outline when documenting within the wolfssl library in doxygen shoul look like as follows: /*! - \ingroup //if API should be in a seperate module + \ingroup //if API should be in a separate module \brief @@ -171,12 +171,10 @@ look like as follows: \sa */ -When adding new documentation be sure to keep the secions, \ingroup, \brief, -\param, \return, Etc. seperated with at least 1 newline. This insures that when -doxygen attempts to generate documentation the sections do not overlap eachother -and produce errors (this is especialy important when the latex is being generated). +When adding new documentation be sure to keep the sections, \ingroup, \brief, +\param, \return, Etc. separated with at least 1 newline. This insures that when +doxygen attempts to generate documentation the sections do not overlap each other +and produce errors (this is especially important when the latex is being generated). Once finished creating new documentation it is highly recommended to generate new html and pdf to ensure no errors were introduced that prevent documentation generation and that the documentation shows up correctly. - - diff --git a/doc/check_api.sh b/doc/check_api.sh new file mode 100755 index 000000000..4b6aa8b77 --- /dev/null +++ b/doc/check_api.sh @@ -0,0 +1,43 @@ +#!/bin/sh + +ls ./dox_comments/header_files/ | +while read h_file; do + grep -P -h -z -o 'WOLFSSL_API(\n|\s|[^;])*;' ./dox_comments/header_files/$h_file | + tr '\n' ' ' | + sed 's/\\n//g' | + sed 's/ \+/ /g' | + sed 's/\x00/\n/g' > dox_api.txt + + find ../ -not -path '../doc/*' -name $h_file | + while read -r h_file_path; do + echo "Checking: $h_file_path" + grep -P -h -z -o 'WOLFSSL_API(\n|\s|[^;])*;' "$h_file_path" | + sed 's/#.*/ /g' | + tr '\n' ' ' | + sed 's/\\n//g' | + sed 's/ \+/ /g' | + sed 's/\x00/\n/g' > wolf_api.txt + + api_count="$(wc -l < dox_api.txt)" + match_count="$(grep -Ff dox_api.txt wolf_api.txt | wc -l)" + if [ "$api_count" != "$match_count" ]; then + echo "Mistmatch" + echo "Dox_api: $api_count" + echo "Matched_api: $match_count" + echo "Header file: $h_file" + echo "Check API: " + sort dox_api.txt -o dox_api.txt + sort wolf_api.txt -o wolf_api.txt + comm -23 dox_api.txt wolf_api.txt + exit 1 + else + echo "$h_file is all good" + break + fi + done || exit 1 + echo 'Next...\n' + +done || exit 1 + +rm dox_api.txt +rm wolf_api.txt diff --git a/doc/dox_comments/header_files/aes.h b/doc/dox_comments/header_files/aes.h index 2e7080d59..d65f1a1f2 100644 --- a/doc/dox_comments/header_files/aes.h +++ b/doc/dox_comments/header_files/aes.h @@ -153,7 +153,8 @@ WOLFSSL_API int wc_AesCbcDecrypt(Aes* aes, byte* out, and decryption. User should differentiate between Aes structures for encrypt/decrypt. - \return none + \return int integer values corresponding to wolfSSL error or success + status \param aes pointer to the AES object used to decrypt data \param out pointer to the output buffer in which to store the cipher @@ -183,7 +184,7 @@ WOLFSSL_API int wc_AesCbcDecrypt(Aes* aes, byte* out, \sa wc_AesSetKey */ - WOLFSSL_API void wc_AesCtrEncrypt(Aes* aes, byte* out, + WOLFSSL_API int wc_AesCtrEncrypt(Aes* aes, byte* out, const byte* in, word32 sz); /*! \ingroup AES diff --git a/doc/dox_comments/header_files/ecc.h b/doc/dox_comments/header_files/ecc.h index 7af35c4e8..942351ef6 100644 --- a/doc/dox_comments/header_files/ecc.h +++ b/doc/dox_comments/header_files/ecc.h @@ -474,7 +474,7 @@ int wc_ecc_init(ecc_key* key); \brief This function frees an ecc_key object after it has been used. - \return none No returns. + \return int integer returned indicating wolfSSL error or success status. \param key pointer to the ecc_key object to free @@ -488,7 +488,7 @@ int wc_ecc_init(ecc_key* key); \sa wc_ecc_init */ WOLFSSL_API -void wc_ecc_free(ecc_key* key); +int wc_ecc_free(ecc_key* key); /*! \ingroup ECC @@ -745,7 +745,6 @@ int wc_ecc_point_is_at_infinity(ecc_point *p); \sa none */ -#ifndef WOLFSSL_ATECC508A WOLFSSL_API int wc_ecc_mulmod(mp_int* k, ecc_point *G, ecc_point *R, mp_int* a, mp_int* modulus, int map); diff --git a/doc/dox_comments/header_files/evp.h b/doc/dox_comments/header_files/evp.h index 339a9d679..0a1bd1547 100644 --- a/doc/dox_comments/header_files/evp.h +++ b/doc/dox_comments/header_files/evp.h @@ -122,7 +122,8 @@ WOLFSSL_API int wolfSSL_EVP_DigestInit_ex(WOLFSSL_EVP_MD_CTX* ctx, WOLFSSL_API int wolfSSL_EVP_CipherInit_ex(WOLFSSL_EVP_CIPHER_CTX* ctx, const WOLFSSL_EVP_CIPHER* type, WOLFSSL_ENGINE *impl, - unsigned char* key, unsigned char* iv, + const unsigned char* key, + const unsigned char* iv, int enc); /*! \ingroup openSSL diff --git a/doc/dox_comments/header_files/logging.h b/doc/dox_comments/header_files/logging.h index ae715e44b..12a954233 100644 --- a/doc/dox_comments/header_files/logging.h +++ b/doc/dox_comments/header_files/logging.h @@ -33,3 +33,44 @@ \sa wolfSSL_Debugging_OFF */ WOLFSSL_API int wolfSSL_SetLoggingCb(wolfSSL_Logging_cb log_function); +/*! + \ingroup Debug + + \brief If logging has been enabled at build time this function turns on + logging at runtime. To enable logging at build time use --enable-debug + or define DEBUG_WOLFSSL. + + \return 0 upon success. + \return NOT_COMPILED_IN is the error that will be returned if logging + isn’t enabled for this build. + + \param none No parameters. + + _Example_ + \code + wolfSSL_Debugging_ON(); + \endcode + + \sa wolfSSL_Debugging_OFF + \sa wolfSSL_SetLoggingCb +*/ +WOLFSSL_API int wolfSSL_Debugging_ON(void); +/*! + \ingroup Debug + + \brief This function turns off runtime logging messages. If they’re + already off, no action is taken. + + \return none No returns. + + \param none No parameters. + + _Example_ + \code + wolfSSL_Debugging_OFF(); + \endcode + + \sa wolfSSL_Debugging_ON + \sa wolfSSL_SetLoggingCb +*/ +WOLFSSL_API void wolfSSL_Debugging_OFF(void); diff --git a/doc/dox_comments/header_files/ssl.h b/doc/dox_comments/header_files/ssl.h index 2b7dedfda..5259c6d83 100644 --- a/doc/dox_comments/header_files/ssl.h +++ b/doc/dox_comments/header_files/ssl.h @@ -4464,7 +4464,17 @@ WOLFSSL_API long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg( \return val Returns the updated options mask value stored in ssl. - \param ssl WOLFSSL structure to set options mask. + \param s WOLFSSL structure to set options mask. + \param op This function sets the options mask in the ssl. + Some valid options are: + SSL_OP_ALL + SSL_OP_COOKIE_EXCHANGE + SSL_OP_NO_SSLv2 + SSL_OP_NO_SSLv3 + SSL_OP_NO_TLSv1 + SSL_OP_NO_TLSv1_1 + SSL_OP_NO_TLSv1_2 + SSL_OP_NO_COMPRESSION _Example_ \code @@ -4479,7 +4489,7 @@ WOLFSSL_API long wolfSSL_CTX_set_tlsext_opaque_prf_input_callback_arg( \sa wolfSSL_free \sa wolfSSL_get_options */ -WOLFSSL_API unsigned long wolfSSL_set_options(WOLFSSL *s, unsigned long op); +WOLFSSL_API long wolfSSL_set_options(WOLFSSL *s, long op); /*! \ingroup Setup @@ -4501,7 +4511,7 @@ WOLFSSL_API unsigned long wolfSSL_set_options(WOLFSSL *s, unsigned long op); \sa wolfSSL_free \sa wolfSSL_set_options */ -WOLFSSL_API unsigned long wolfSSL_get_options(const WOLFSSL *s); +WOLFSSL_API long wolfSSL_get_options(const WOLFSSL *s); /*! \ingroup Setup @@ -5157,47 +5167,6 @@ WOLFSSL_API const char* wolfSSL_lib_version(void); \sa wolfSSL_lib_version */ WOLFSSL_API unsigned int wolfSSL_lib_version_hex(void); -/*! - \ingroup Debug - - \brief If logging has been enabled at build time this function turns on - logging at runtime. To enable logging at build time use --enable-debug - or define DEBUG_WOLFSSL. - - \return 0 upon success. - \return NOT_COMPILED_IN is the error that will be returned if logging - isn’t enabled for this build. - - \param none No parameters. - - _Example_ - \code - wolfSSL_Debugging_ON(); - \endcode - - \sa wolfSSL_Debugging_OFF - \sa wolfSSL_SetLoggingCb -*/ -WOLFSSL_API int wolfSSL_Debugging_ON(void); -/*! - \ingroup Debug - - \brief This function turns off runtime logging messages. If they’re - already off, no action is taken. - - \return none No returns. - - \param none No parameters. - - _Example_ - \code - wolfSSL_Debugging_OFF(); - \endcode - - \sa wolfSSL_Debugging_ON - \sa wolfSSL_SetLoggingCb -*/ -WOLFSSL_API void wolfSSL_Debugging_OFF(void); /*! \ingroup IO