README_DOXYGEN
1wolfSSL with Doxygen 1.8.13
2
3---- Dependencies ----
4
5cmake
6make
7git
8latex-see below (With pdflatex included. However the pdflatex dependency can be removed by
9setting USE_PDFLATEX to NO in the file "Doxyfile" located at
10doc/formats/pdf/Doxyfile )
11
12The following texlive packages were installed when creating this
13documentation on Linux Mint:
14sudo apt install texlive
15sudo apt install texlive-latex-extra
16
17For Mac users Basic Tex from TUG is recommended. After installing BasicTex
18additional dependencies will need to be met:
19% sudo tlmgr update --self
20% sudo tlmgr install tabu varwidth multirow adjustbox collectbox sectsty tocloft collection-fontsextra
21
22---- Generating the Documentation ----
23
24If you are looking to just generate the html documentation and not interested in
25how to add your own just run one of the following commands from the main wolfssl
26directory:
27
28 make dox (this option will make both html and pdf documentation)
29 make dox-html (only html documentation)
30 make dox-pdf (only pdf documentation)
31
32If it is the first time running one of the above commands the command will take
33some time to run. This is because the doxygen repository must be clones and then
34built along with the time taken to make the documentation.
35
36Once documentation generation has completed to open the html use a browser to
37open doc/html/index.html. To open the generated pdf looking for
38refman.pdf located and doc/refman.pdf.
39
40---- Configure ----
41
42Doxygen uses a file called "Doxyfile" to hold all its values for configuration.
43If needed, to generate a fresh Doxfile run the command
44
45 doxygen -g
46
47Once a Doxyfile is generate there are a few options to keep in mind.
48Below are some the the settings that are currently used:
49
50 EXTRACT_ALL
51
52 - this option determines if all API are extracted or just API that is documented.
53
54 OPTIMIZE_OUTPUT_FOR_C
55
56 - changes the look and naming schemes used in generated documentation.
57
58 RECURSIVE
59
60 - allows doxygen to search subdirectories in a library for documenting.
61
62 GENERATE_LATEX
63
64 - tells doxygen whether or not to generate LATEX documentation. The Latex
65 that is generated is used to generate a PDF as well.
66
67 ENABLE_PREPROCESSING
68
69 - tells doxygen whether or not to ignore C/C++ preprocessors directives i.e #ifdef, #ifndef
70
71 EXCLUDE
72
73 - allows the user to specify files or directories to ignore when documenting.
74
75 HTML_EXTRA_STYLESHEET
76
77 -allows the user to specify their own css style sheet to use for the doxygen html.
78
79 SHOW_USED_FILES and SHOW_FILES
80
81 - when using groups it is important to keep these options set to yes otherwise
82 functions with documentation that are not part of a group may fail to be included
83 in the generated documentation.
84
85---- Embedding Documentation ----
86
87Doxygen API documentation should be placed in the doc/dox_comments/
88directory. The documentation should be stored in a file in this directory with the
89same name of the file in which the API resides in the wolfssl repository. C code
90header files (*.h) should be used when writing the API documentation. If API in a
91file is being documented for the first time be sure to add the to the top of the
92original file:
93
94 /*!
95 \file wolfssl/PATH_TO_FILE/FILE_NAME
96 */
97
98This ensures that the file will be linked to in the doxygen generated html.
99When specifying a specific file with the \file command be sure to include part of
100the file's path so that it is a unique name. This allows for linking to files even
101when multiple files share the same name.
102
103To ensure that doxygen documents a specific API in to a desired module be sure
104to include that module's name in the \ingroup. The current modules to choose from
105are as follows but new group can be made:
106
107 \ingroup 3DES
108 \ingroup AES
109 \ingroup ARC4
110 \ingroup BLAKE2
111 \ingroup Camellia
112 \ingroup ChaCha
113 \ingroup ChaCha20Poly1305
114 \ingroup Curve25519
115 \ingroup DSA Algorithms
116 \ingroup Diffie-Hellman
117 \ingroup ECC
118 \ingroup ED25519
119 \ingroup HC128
120 \ingroup HMAC
121 \ingroup IDEA
122 \ingroup MD2
123 \ingroup MD4
124 \ingroup MD5
125 \ingroup PKCS7
126 \ingroup Password
127 \ingroup Poly1305
128 \ingroup RIPEMD
129 \ingroup RSA
130 \ingroup Rabbit
131 \ingroup SHA
132 \ingroup SRP
133 \ingroup wolfCrypt
134 \ingroup openSSL
135 \ingroup CertManager
136 \ingroup TLS
137 \ingroup CertsKeys
138 \ingroup Setup
139 \ingroup IO
140 \ingroup Debug
141
142If one of the above modules/ groups does not fit a desired function then a new
143group will need to be created. To do this include add a new group definition
144to the doxygen_groups.h file located at documentation/formats/pdf/doxygen_groups.h
145
146 /*!
147 \defgroup <group name> <description>
148 */
149
150The general outline when documenting within the wolfssl library in doxygen should
151look like as follows:
152
153 /*!
154 \ingroup //if API should be in a separate module
155
156 \brief <description of API>
157
158 \return <name of return> <description> // each return will need \return.
159
160 \param <name of param> <description> // stands for parameter, each parameter will need \param.
161
162 _Example_
163 \code
164 // any example code here
165 \endcode
166
167 \sa // stands for see also. Each API reference here should begin with \sa
168 \sa <Function>
169 \sa <Function>
170 */
171
172When adding new documentation be sure to keep the sections, \ingroup, \brief,
173\param, \return, Etc. separated with at least 1 newline. This insures that when
174doxygen attempts to generate documentation the sections do not overlap each other
175and produce errors (this is especially important when the latex is being generated).
176Once finished creating new documentation it is highly recommended to generate new
177html and pdf to ensure no errors were introduced that prevent documentation
178generation and that the documentation shows up correctly.
179