1/11/2024 0 Comments Doxygen comment examples![]() ![]() Since the variable name radius is obvious to the reader of the code, I did not add the description. Please have a look at my other article When to use and when to avoid comments? for guidelines on commenting. ![]() The following sections provide guidelines for OpenOCD developers who wish to write Doxygen comments in the code or this manual.įor an introduction to Doxygen documentation, see the Doxygen Primer.Since the variable name radius is obvious to the reader of the code, I did not add the description. Several different types of Doxygen comments can be used often, one style will be the most appropriate for a specific context. for documentation requiring multiple lines, use a "block" style: /**.use /// to for one-line documentation of instances.The following guidelines provide developers with heuristics for selecting an appropriate form and writing consistent documentation comments. * in blocks such as the one in which this example appears in the Style * One can make text appear in italics, bold, monospace, or * the full description block, where "empty" lines start new paragraphs. See the Doxygen Manual for the full list of commands. * foo For a function, describe the parameters (e.g. In addition to the guidelines in the preceding sections, the following additional style guidelines should be considered when writing documentation as part of standalone text files:Ĭode examples provided in documentation must conform to the Style Guide.Two spaces should be used when nesting lists do not use '\t' in lists.To mark-up multiple words, the HTML alternatives must be used.(monospace) should be used with file names and code symbols, so they appear visually distinct from surrounding text.(bold) should be used to emphasizing single words.(italics) should be used to reference parameters (e.g.use in other contexts to create links to pages and sections.new pages can be linked into the hierarchy by using the command somewhere the page(s) under which they should be linked.URLS get converted to markup automatically, without any extra effort.struct_name::member_name should be used to reference structure fields in the documentation (e.g.function_name() can be used to reference functions (e.g.Use symbol names such that Doxygen automatically creates links.Use the form for all doxygen commands (do not use '\cmd').The following guidelines apply to all Doxygen comment blocks: This style should be used sparingly the best use is for fields: int field /**The /**If the total line length will be less than 72-80 columns, then.Only single spaces should be used do not add mid-line indentation.Except to separate paragraphs of documentation, other extra "empty" lines should be removed from the block.A single "empty" line should separate the function documentation from the block of parameter and return value descriptions.A leading space is required to align the '*' with the /** line.Every line in the block should have a '*' in-line with its start.The end of the block, */, should also be on its own line.The block should start on the line following the opening /**.* The value(s) returned, or possible error conditions. ![]() ![]() Text files must contain Doxygen at least one comment block.Documentation should begin in the first column (except for nested lists). ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |