These included in the header file along with the declaration of the tag supplies a more detailed description. By convention in Rosetta3 all functions must have brief tags. This message should tell what happens in the function. Common Doxygen Tags Common Source Document tag supplies a brief description of a function for doxygen pages.
Comment main.c file for doxygen example code#
To end the comment block type asterik and then forward slash.īy taking a few minutes as you are writing your code to write comment blocks you can tell future developers what you intended and make their life more productive and easier. To start a new paragraph add an empty line These next few lines will form a comment block ///This line will be included in the Doxygen comments for this function/class/fileĬommenting multiple lines is just as easy. For line comment just insert a triple forward slash. Template Doxygen Page for Documenting an Applicationĭoxygen comment blocks are easy to create.Template page for Subdirectories of Libraries.Template Doxygen Page for New Category of Source Files.Each of the below template pages are found in doc/template_doxygen_pages. On the simplest level you can copy them to an appropriate location and fill in the fields with the appropriate information.
These pages are intended as starting points.
Writing Descriptive Comments in DoxygenĪ few general template doxygen pages have been created to help you document higher level concepts in Rosetta.For example, IMAGE_PATH is set to the root of the project.įor more information on customizing these settings, please see rosdoc. You can " roscd rosdoc" and look at the templates/doxy.template to see the many of the default settings used with Doxygen. By default, this is:įILE_PATTERNS: *.c *.cpp *.h *.cc *.hh *.py *.dox The most important is FILE_PATTERNS: these are the files that Doxygen will look inside of for documentation. Rosdoc comes with default settings that generally work well with packages in ROS. Please use the \todo tag wherever applicable. This is better than using //TODO or //FIXME or whatever other comments you might normally use, because it makes the todo-ness externally visible. */ĭoxygen provides a \todo tag, that can be used in any Doxygen-style comment block, e.g.: /** Make the value externally configurable */ĭoxygen collects these tags into a "related page," providing a nice reference for remaining work. String* name /**< A variable that is the coolest. Int error_number /**< A variable that can be confused with the other variable. * \param junk This is a cool junk varible * This description is displayed lower in the doxygen as an extended description along with * \brief This description shows up at the top of the doxygen so you don't have to scroll. Here is an example geared toward a class that is likely compiled into a library: The \htmlinclude line inputs a nicely formatted version of the package's manifest.xml file.ĭoxygen's main strength is that you can include documentation inline with your code. NOTE: you have to use C++ comment syntax in this file, e.g., : /** Also, if you use the roscreate-pkg tool to create your package, a mainpage.dox will be generated for you. To make things easier, we have created a default template in the rosdoc package, which you can find at rosdoc/templates/. There should only be one mainpage tag in your package, so we usually recommend creating a top-level file, e.g. The first thing you'll probably want to do is use the \mainpage tag. You can use any Doxygen markup in your code.
Comment main.c file for doxygen example how to#
For actual documentation on how to use the Doxygen documentation tool, please see the official Doxygen site. NOTE: this page is not a comprehensive guide to Doxygen. For Python we generally use Epydoc or Sphinx. With ROS packages, we generally use Doxygen to document C++-based code. Instead, we recommend that you use the rosdoc tool, which provides common templating and other features. You don't need to configure and run Doxygen manually in order to generate documentation for your ROS package. Doxygen searches for source code in your tree and generates API documentation for it. The main advantage of Doxygen is that you can write documentation directly within the comments of your source code. Doxygen is a tool for auto-generating API documentation, though you can also use it to generate documentation separate from an API.
0 kommentar(er)
