Migrated documentation directory to doc. README updated. Error fixes. Moved make options to doc/include.am
This commit is contained in:
connerwolfssl
parent
f5c33a9362
commit
17e88b47f6
17
Makefile.am
17
Makefile.am
@ -150,14 +150,6 @@ tests/unit.log: testsuite/testsuite.log
|
||||
DISTCLEANFILES+= cyassl-config
|
||||
DISTCLEANFILES+= wolfssl-config
|
||||
|
||||
clean-local:
|
||||
-rm -rf documentation/build/
|
||||
-rm -rf documentation/html/
|
||||
-rm -f documentation/refman.pdf
|
||||
-rm -f documentation/doxygen_warnings
|
||||
-rm -f documentation/doxygen_html_warnings
|
||||
-rm -f documentation/doxygen_pdf_warnings
|
||||
|
||||
maintainer-clean-local:
|
||||
-rm Makefile.in
|
||||
-rm aclocal.m4
|
||||
@ -216,12 +208,3 @@ merge-clean:
|
||||
@find ./ | $(GREP) \.BASE | xargs rm -f
|
||||
@find ./ | $(GREP) \~$$ | xargs rm -f
|
||||
|
||||
dox-pdf:
|
||||
echo "Generating PDF"
|
||||
cd documentation && ./generate_documentation.sh -pdf > ./doxygen_pdf_warnings || (echo "HTML generation failed $$?"; exit 1)
|
||||
|
||||
dox-html:
|
||||
echo "Generating HTML"
|
||||
cd documentation && ./generate_documentation.sh -html > ./doxygen_html_warnings || (echo "HTML generation failed $$?"; exit 1)
|
||||
|
||||
dox: dox-html dox-pdf
|
||||
|
||||
@ -5,9 +5,21 @@ wolfSSL with Doxygen 1.8.13
|
||||
cmake
|
||||
make
|
||||
git
|
||||
latex (with pdflatex included)
|
||||
( The pdflatex dependency can be removed by setting USE_PDFLATEX to NO in the
|
||||
file "Doxyfile" located at documentation/formats/pdf/Doxyfile )
|
||||
latex (With pdflatex included. However the pdflatex dependency can be removed by
|
||||
setting USE_PDFLATEX to NO in the file "Doxyfile" located at
|
||||
doc/formats/pdf/Doxyfile )
|
||||
|
||||
The following texlive packages were used when creating this
|
||||
documentation:
|
||||
texlive [installed]
|
||||
texlive-base [installed,automatic]
|
||||
texlive-binaries [installed]
|
||||
texlive-font-utils [installed]
|
||||
texlive-fonts-recommended [installed,automatic]
|
||||
texlive-latex-base [installed,automatic]
|
||||
texlive-latex-extra [installed]
|
||||
texlive-latex-recommended [installed]
|
||||
texlive-pictures [installed,automatic]
|
||||
|
||||
---- Generating the Documentation ----
|
||||
|
||||
@ -24,8 +36,8 @@ some time to run. This is because the doxygen repository must be clones and then
|
||||
built along with the time taken to make the documentation.
|
||||
|
||||
Once documentation generation has completed to open the html use a browser to
|
||||
open documentation/html/index.html. To open the generated pdf looking for
|
||||
refman.pdf located and documentation/refman.pdf.
|
||||
open doc/html/index.html. To open the generated pdf looking for
|
||||
refman.pdf located and doc/refman.pdf.
|
||||
|
||||
---- Configure ----
|
||||
|
||||
@ -74,7 +86,7 @@ Below are some the the settings that are currently used:
|
||||
|
||||
---- Embedding Documentation ----
|
||||
|
||||
Doxygen API documentation should be placed in the documentation/dox_comments/
|
||||
Doxygen API documentation should be placed in the doc/dox_comments/
|
||||
directory. The documentation should be stored in a file in this directory with the
|
||||
same name of the file in which the API resides in the wolfssl repository. C code
|
||||
header files (*.h) should be used when writing the API documentation. If API in a
|
||||
@ -62,7 +62,7 @@ WOLFSSL_API int wc_CamelliaSetKey(Camellia* cam,
|
||||
\endcode
|
||||
|
||||
\sa wc_CamelliaSetKey
|
||||
*/
|
||||
*/
|
||||
WOLFSSL_API int wc_CamelliaSetIV(Camellia* cam, const byte* iv);
|
||||
/*!
|
||||
\ingroup Camellia
|
||||
@ -115,7 +115,7 @@ WOLFSSL_API int wc_CamelliaEncryptDirect(Camellia* cam, byte* out,
|
||||
byte decrypted[16];
|
||||
|
||||
wc_CamelliaDecryptDirect(&cam, decrypted, cipher);
|
||||
\endode
|
||||
\endcode
|
||||
|
||||
\sa wc_CamelliaEncryptDirect
|
||||
*/
|
||||
@ -741,6 +741,7 @@ int wc_ecc_point_is_at_infinity(ecc_point *p);
|
||||
mp_int multiplicand;
|
||||
mp_int modulus;
|
||||
int map;
|
||||
\endcode
|
||||
|
||||
\sa none
|
||||
*/
|
||||
@ -72,9 +72,9 @@
|
||||
\fancyhead[RO]{\fancyplain{}{\bfseries\thepage}}
|
||||
\fancyfoot[LE]{\fancyplain{}{}}
|
||||
\fancyfoot[CE]{\fancyplain{}{}}
|
||||
\fancyfoot[RE]{\fancyplain{}{\bfseries\scriptsize Copyright © 2017 wolfSSL Inc.
|
||||
\fancyfoot[RE]{\fancyplain{}{\bfseries\scriptsize Copyright © 2018 wolfSSL Inc.
|
||||
All rights reserved. }}
|
||||
\fancyfoot[LO]{\fancyplain{}{\bfseries\scriptsize Copyright © 2017 wolfSSL Inc.
|
||||
\fancyfoot[LO]{\fancyplain{}{\bfseries\scriptsize Copyright © 2018 wolfSSL Inc.
|
||||
All rights reserved. }}
|
||||
\fancyfoot[CO]{\fancyplain{}{}}
|
||||
\fancyfoot[RO]{\fancyplain{}{}}
|
||||
@ -24,17 +24,8 @@ echo "Please install make"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ ! -e "build" ]; then
|
||||
echo "build directory not present...creating directory..."
|
||||
mkdir build
|
||||
cd build
|
||||
echo "cloning doxygen 1.8.13..."
|
||||
git clone https://github.com/doxygen/doxygen --branch Release_1_8_13
|
||||
cmake -G "Unix Makefiles" doxygen/
|
||||
make
|
||||
cd ..
|
||||
else
|
||||
if [ ! -e "build/bin/doxygen" ]; then
|
||||
mkdir -p build
|
||||
cd build
|
||||
echo "cloning doxygen 1.8.13..."
|
||||
git clone https://github.com/doxygen/doxygen --branch Release_1_8_13
|
||||
@ -42,7 +33,6 @@ cmake -G "Unix Makefiles" doxygen/
|
||||
make
|
||||
cd ..
|
||||
fi
|
||||
fi
|
||||
|
||||
if [ $1 = "-html" ] || [ $1 = "-all" ]; then
|
||||
#HTML GENERATION
|
||||
@ -50,13 +40,14 @@ cp -r formats/html/* ./
|
||||
echo "generating html..."
|
||||
build/bin/doxygen Doxyfile
|
||||
cp html_changes/search/* html/search/
|
||||
cp html_changes/* html/
|
||||
cp html_changes/*.css html/
|
||||
cp html_changes/*.js html/
|
||||
rm footer.html header.html
|
||||
rm -rf html_changes
|
||||
rm mainpage.dox
|
||||
rm Doxyfile
|
||||
echo "finished generating html..."
|
||||
echo "To view the html files use a browser to open the index.html file located at documentation/html/index.html"
|
||||
echo "To view the html files use a browser to open the index.html file located at doc/html/index.html"
|
||||
fi
|
||||
|
||||
#PDF GENERATION
|
||||
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 25 KiB |
@ -3,3 +3,21 @@
|
||||
# All paths should be given relative to the root
|
||||
|
||||
dist_doc_DATA+= doc/README.txt
|
||||
|
||||
dox-pdf:
|
||||
echo "Generating PDF"
|
||||
cd doc && ./generate_documentation.sh -pdf > ./doxygen_pdf_warnings || (echo "HTML generation failed $$?"; exit 1)
|
||||
|
||||
dox-html:
|
||||
echo "Generating HTML"
|
||||
cd doc && ./generate_documentation.sh -html > ./doxygen_html_warnings || (echo "HTML generation failed $$?"; exit 1)
|
||||
|
||||
dox: dox-html dox-pdf
|
||||
|
||||
clean-local:
|
||||
-rm -rf doc/build/
|
||||
-rm -rf doc/html/
|
||||
-rm -f doc/refman.pdf
|
||||
-rm -f doc/doxygen_warnings
|
||||
-rm -f doc/doxygen_html_warnings
|
||||
-rm -f doc/doxygen_pdf_warnings
|
||||
|
||||
@ -1,133 +0,0 @@
|
||||
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 ----
|
||||
|
||||
Doxygen stype API documentation should be placed in the documentation/dox_comments/
|
||||
directory. The documentation should be stored in a file in this directory with the
|
||||
same name of the file in which the API resides in the wolfssl repository. C code
|
||||
header files (*.h) should be used when writing the API documentation. If API in a
|
||||
file is documented be sure to add the the top of the original file:
|
||||
/*!
|
||||
\file wolfssl/PATH_TO_FILE/FILE_NAME
|
||||
*/
|
||||
|
||||
This ensures that the file will be linked to in the doxygen generated html.
|
||||
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 as follows but new group can be made:
|
||||
\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.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user