README_DOXYGEN 5.7 KB

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