![]() * This product includes software developed by the However, you can make this even more useful by embedding documentation on how to use your classes right in the code itself. The following guidelines were extracted from "MINOS Offline Documentation, How to document your code for doxygen" here and modified to reflect the LSST Doxygen standard for C++.ĭoing nothing, Doxygen will produce a nice cross referenced HTML-ized version of the code. Method parameter documentation must remain consistent with the method argument declaration. Use one-line, inline comments to document arguments in the method definition only if all methods in the source file are documented similarly. Acceptable Documentation Style with Constraints Use /* to start and */ to end a comment block. or Strongly Preferred Documentation Style Use to precede all doxygen special commands. Thus most doxygen documentation will be in header files. When deciding where to document an object, place the doxygen documentation where the item is declared. The following guidelines should be followed for LSST C++ source files. Be aware that LSST makes use of Doxygen's Markdown support for text formatting please mark up your documentation appropriately.use the special command which uses block formatting for visual impact.For C++, to annotate note-worthy information.This allows Doxygen to report on all such events occurring in the code - thus ensuring we don't forget to go back to handle the set-aside issues. For C++, to annotate issues which need to be addressed in the future.Document each function and each of its arguments.For files that do not contain classes, (ie, just functions). ![]() provide similar information as for C++ but use docstrings formatted using doxygen markup tags.For python, followng each class specification.Document each argument to methods and constructors.Document each constructor, public instance variable, and public method.Describe the class' purpose in a longer block.Provide the brief (1-line) comment used in the doxygen 'Classes' content index.Use to start the class documentation block.For C++, Preceding each class specification.For source files containing class specifications.For python use docstrings to provide the file contents description.Followed by a longer description for the file's Detailed Description.Then provide a brief (1-line) comment for the doxygen 'Files' content index.py) should briefly describe the purpose of the code contained within. The LSST Copyright statement appropriate for the file type.The beginning of each source file should start with.Detailed discussion relative to a specific language is provided for C++ and Python. The following is the general guideline for documenting source code for LSST. The doxygen manual is available for specific questions about Doxygen. LSST uses doxygen as its primary source code documentation generator tool.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |