5. Software documentation image/svg+xml 5. Software documentation Zidarics Zoltánzamek@vili.pmmf.hu 2020 Software documentation EmbeddedProgramming 4.testing 6.complex datastructures Problem software maintenance what modules are included in a software? what functions are there in a module? What are the input and output parameters of a function? what return value does a function give? what is the purpose of a module? does a function allocate memory? answers can only be obtained by reading the code Solution API (Application Programming Interface) API documentation is part of the software module management different formats (html, Latex, rtf, man, XML, Docbook) Doxygen installing: apt-get install doxygen doxygen-gui configuration file: doxyfile documentation simple text file gui interface: doxywizard Doxygen Sources Custom - headers - footers - images Doxygen Tag file(s) Layout file Config file Doxyfile Doxywizard generate/edit XML files Latex files+Makefile Man pages refman.rft HTMLpages read import Windows only MS Word doc chm HTML Help Workshop make pdf make ps latex postscript PDF customoutput read generate read read read read generate generateupdate Your application doxmlparser lib Generation of documentation supported languages: C, C ++, C #, Objective C,IDL, Java, VHDL, PHP, Python, Tcl, Fortran, D generate configuration file: doxygen -g <config-file> configuration: text editor or doxywizard documentation generation: doxygen Documenting the code documentation of modules and functions special doxygen annotations in doxygen comments doxygen comment in lines between / ** * / /** * * \brief Demonstrating tailq as a normal queue;  There are two process, a producer and a consumer. Producer produce some data asynchronous, and p There is a process as a consumer, which is gets products from the queue, if its not empty.  \author Zamek \version 1.0 * */ /** * Order a pizza. * * If the pizza isn't in the queue it returns NULL * Caller must free the allocated pizza if the result isn't NULL. * * \param index Menu index of the wanted pizza. Accepted value is 0 up to size of menu. * Out of index ordered returns will be NULL * \return Pointer to the element of queue or NULL if it cannot found in the queue. */struct pizza_t *pizzeria_order(int index);  Alternate annotations /*! * ... text ... */ /// /// ... text .../// //! //! ... text ...//! /** @defgroup group1 The First Group * This is the first group * @{ *//** @brief struct C1 in group 1 */struct C1 {};/** @brief class C2 in group 1 */struct C2 {};/** function in group 1 */void func() {}/** @} */ // end of group1/** * @defgroup group2 The Second Group * This is the second group *//** @defgroup group3 The Third Group * This is the third group *//** @defgroup group4 The Fourth Group * @ingroup group3 * Group 4 is a subgroup of group 3 *//** * @ingroup group2 * @brief struct C3 in group 2 */struct C3 {};/** @ingroup group2 * @brief class C4 in group 2 */struct C4 {};/** @ingroup group3 * @brief struct C5 in @link group3 the third group@endlink. */struct C5 {};/** @ingroup group1 group2 group3 group4 * namespace N1 is in four groups * @sa @link group1 The first group@endlink, group2, group3, group4 * * Also see @ref mypage2 */namespace N1 {};/** @file * @ingroup group3 * @brief this file in group 3 *//** @defgroup group5 The Fifth Group * This is the fifth group * @{ *//** @page mypage1 This is a section in group 5 * Text of the first section *//** @page mypage2 This is another section in group 5 * Text of the second section *//** @} */ // end of group5/** @addtogroup group1 * * More documentation for the first group. * @{ *//** another function in group 1 */void func2() {}/** yet another function in group 1 */void func3() {}/** @} */ // end of group1 Module documentation a set of logically related objects in multiple files group members can be functions, variables, listed types, type definitions group related annotations, defgroup, addtogroup, ingroup /** \mainpage My Personal Index Page * * \section intro_sec Introduction * * This is the introduction. * * \section install_sec Installation * * \subsection step1 Step 1: Opening the box * * etc... */ Main page doxygen block \mainpage annotation will be the index page of the documentation /*! * A list of events: * <ul> * <li> mouse events * <ol> * <li>mouse move event * <li>mouse click event<br> * More info about the click event. * <li>mouse double click event * </ol> * <li> keyboard events * <ol> * <li>key down event * <li>key up event * </ol> * </ul> * More text here. */ Manage lists at the beginning of the line - causes the list to be listed /** * Text before the list * - list item 1 * - sub item 1 * - sub sub item 1 * - sub sub item 2 * . * The dot above ends the sub sub item list. * * More text for the first sub item * . * The dot above ends the first sub item. * * More text for the first list item * - sub item 2 * - sub item 3 * - list item 2 * . * More text in the same paragraph. * * More text in a new paragraph. */ you can also use + or * characters html is also allowed: Manage Formulas Latex format formulas by default The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.  The distance between is and Macro preprocessor built-in simplified preprocessor #define VERSION 200#define CONST_STRING const char * #if VERSION >= 200 static CONST_STRING version = "2.xx";#else static CONST_STRING version = "1.xx";#endif  result: #define VERSION#define CONST_STRING  static CONST_STRING version = "2.xx";  if we change the ENABLE_PREPROCESSING variable in the doxyfile to NO: #define VERSION#define CONST_STRING  static CONST_STRING version = "2.xx"; static CONST_STRING version = "1.xx";  Automatic link generation there may be "look at this" sections in the documentation link to the object <a href="linkURL">link text</a> Doxygen automatically detects URLs and email addresses and converts a link manual entry \ref <name> ["(text)"] /** Return a malloc'd copy of at most N bytes of STRING. The resultant string is terminated even if no null terminator appears before STRING[N].  \ref strdup see strdup \param __string string to duplicate\param __n max length of string\return new copied string*/extern char *strndup (const char *__string, size_t __n) __THROW __attribute_malloc__ __nonnull ((1));  callgraph \callgraph generates a call diagram if the HAVE_DOT option is turned on in the config file P3_MakeDemo projekt callergraph \ callergrah generates a bar chart when the HAVE_DOT option is turned on in the config file P3_MakeDemo project /*! \def MAX(x,y) Computes the maximum of \a x and \a y.*//*! Computes the absolute value of its argument \a x.*/#define ABS(x) (((x)>0)?(x):-(x))#define MAX(x,y) ((x)>(y)?(x):(y))#define MIN(x,y) ((x)>(y)?(y):(x))   Documenting macros \def <name> /**\enum WeekDays*/enum WeekDays { monday=0, tuesday, wednesday, thirsday, friday, saturday, sunday };  Documentation of enumerations \enum <name> Documenting deprecated objects \deprecated { description } /** * Old style processing of Module A * Please do not use it in a new project! * \deprecated { plese use #module_a_process() instead of this } * \return EXIT_SUCCESS if everything is ok or EXIT_FAILURE when error occured */int module_a_oldstyle_process(); objects reserved for compatibility reasons cannot be used in new development Paste snippets /** \example example_test.c * This is an example of how to use the Example_Test module. * More details about this example. */ insert full source files, path defined in the EXAMPLE_PATH variable in the config file \example <file-name> \code [{<word>}] /** * processing by module A * * Example: * \code{.c} * * int result = module_a_process(); * if (result != EXIT_SUCCESS) * abort(); * * \endcode * * \return EXIT_SUCCESS if everything is ok or EXIT_FAILURE when error occured */int module_a_process(); /** \bug { there are some memory leaking at module_a_init. Bug id #3/2016 } */ Documenting bugs \bug { bug description } Documenting unresolved cases /** * init module A * *\todo find the bug of module_a_init() * * \callgraph * \callergraph * \return EXIT_SUCCESS if everything is ok or EXIT_FAILURE when error occured */int module_a_init(); \todo message will be added to the TODO list Using images /** \image html DrawingHands.jpg "M.Escher: Drawing Hands" */  \image <format> <file> ["caption"] [<sizeindication>=<size>] It takes the path from the IMAGE_PATH configured in the config file format: html,latex,docbook,rtf file: the file name of the image caption: the caption text of the image size: Size of the image in pixels Insert special characters \&\$\#\<\>\%\"\.\::\|\--  e.g. the characters used in html
1
  1. Main
  2. Problem
  3. Solution
  4. Doxygen
  5. Doxygen outline
  6. Generation of documentation
  7. Documenting the code
  8. Alternate annotations
  9. Main page
  10. Modul documentation
  11. Manage lists I.
  12. Manage lists II.
  13. Manage formulas
  14. Macro preprocessor
  15. Automatic link generation
  16. Callgraph
  17. Callergraph
  18. Documenting macros
  19. Documenting enumerations
  20. Deprecated objektumok dokumentálása
  21. Paste snippets
  22. Documenting bugs
  23. Documenting unresolved cases
  24. Using images
  25. Inserting special characters
  26. next