wolfssl/documentation/README

wolfSSL with Doxygen 1.8.13

---- Generating the HTML ----

If you are looking to just generate the html documentation and not interested in
how to add your own just run the GENERATE_HTML.sh script and then open the 
html/index.html file with your preferred browser.

---- Configure ----

Doxygen uses a file called "Doxyfile" to hold all its values for configurations.
If needed to generate a fresh Doxfile run the command 

    doxygen -g
    
Once a Doxyfile is generate there are a few options to keep in mind.
Below are some the the settings that are currently used:

   EXTRACT_ALL

    - this option determines if all API are extracted or just API that is documented.    
    
   OPTIMIZE_OUTPUT_FOR_C

    - changes the look and naming schemes used in generated documentation.
    
   RECURSIVE

    - allows doxygen to search subdirectories in a library for documenting.
    
   GENERATE_LATEX

    - tells doxygen whether or not to generate LATEX documentation.

   GENERATE_MAN

    - tells doxygen whether or not to generate MAN pages.

   ENABLE_PREPROCESSING

    - allows doxygen to include items for preprocessing like #ifdef, #endif, etc.
    
   EXCLUDE
    
    - allows the user to specify files or directories to ignore when documenting.
    
   HTML_EXTRA_STYLESHEET
    
    -allows the user to specify their own css style sheet to use for the doxygen html.

---- Embedding Documentation ----

In the wolfssl repo, doxygen comments should be embedded in header files when possible.
This ensures that code is not too cluttered and keeps API easy to find. If a function 
prototype is not available in a header file then a .c file should be the next choice.

When specifying a specific file with the \file command be sure to include part of
the file's path so that it is a unique name. This allows for linking to files even
when multiple files share the same name.

To ensure that doxygen documents a specific API in to a desired module be sure 
to include that module's name in the \ingroup. The current modules to choose from
are:
    \ingroup 3DES
    \ingroup AES
    \ingroup ARC4
    \ingroup BLAKE2
    \ingroup Camellia
    \ingroup ChaCha
    \ingroup ChaCha20Poly1305
    \ingroup Curve25519
    \ingroup DSA Algorithms
    \ingroup Diffie-Hellman
    \ingroup ECC
    \ingroup ED25519
    \ingroup HC128
    \ingroup HMAC
    \ingroup IDEA
    \ingroup MD2
    \ingroup MD4
    \ingroup MD5
    \ingroup PKCS7
    \ingroup Password
    \ingroup Poly1305
    \ingroup RIPEMD
    \ingroup RSA
    \ingroup Rabbit
    \ingroup SHA
    \ingroup SRP
    \ingroup wolfCrypt
    \ingroup openSSL
    \ingroup CertManager

If one of the above modules/ groups does not fit a desired function then a new 
group will need to be created. To do this include the following at the top of 
the ssl.h file in wolfssl/wolfssl maintaining the alphabetical order:

    /*!
        \defgroup <group name>
    */

The general outline when documenting within the wolfssl library in doxygen should
look like as follows: 

    /*!
        \ingroup //if API should be in a seperate module
        
        \brief <description of API>
        
        \return <name of return> <description> // each return will need \return.
        
        \param <name of param> <description> // stands for parameter, each parameter will need \param.
        
        _Example_
        \code
            // any example code here
        \endcode
        
        \sa // stands for see also. Each API reference here should have its own \sa
    */

Be careful when including extra line breaks. This can throw off the formatting doxygen generates
and may cause undesired misaligned sections in the doxygen generated documentation. It is a good
idea to check how your documentation looks as you work so that mistakes are not repeatedly being made
throughout the documentation process.