Returnsįor functions and class methods, a description of its return value(s), The selfĪrgument to class methods is not documented. With the class, not as part of the _init_ method. For classes, constructor arguments are described here This section must immediately follow the extended summary.ĭescription of the function arguments/keywords, including type ** enabled ** : bool Whether task execution is enabled defaults to True. ** Keywords ** ** stale ** : bool Whether task output BDPs are out of date defaults to True. Presents one set of guidelines for the latter. This document is not a Python coding style guide the Google Python Style They address all three of the items mentioned above. These appear not only to be the most widely known (and used) of theĭocstring-based systems, but ADMIT users are also close to their own userĬommunity. To produce the official user documentation, ADMIT has adopted the Including docstrings verbatim, when doxygen is run. The ADMIT tree contains a DoxyfileĬonfiguration at the top level which will create this tree (in doc/html), Which will automatically generate an indexed HTML tree of syntax-highlighted However, doxygen can still be useful because of its source browser facility, To serve as our primary documentation tool. Independent documentation channel in this case, appearing as pre-formatted Docstrings can still be used but are basically an Markup, instead relying on special comment blocks (starting with #) in a Team and does support Python, it does not parse docstrings for its own Readily accessible in any interactive Python session, this is a very naturalĪlthough Doxygen was very familiar to the ADMIT Since docstrings are object attributes and hence Python documentation packages center around how to structure and process them the manner of presentation of the documentation to the userĪs Python has a built-in docstring facility, most.the physical formatting of the documentation source text.the logical information to include when documenting classes and methods.*! More detailed enum description.In documenting ADMIT’s Python codebase, there are three specific items to You can use the JavaDoc style, which consist of a C-style comment block starting with two *'s, like this: There are several ways to mark a comment block as a detailed description: For the HTML output brief descriptions are also use to provide tooltips at places where an item is referenced. An "in body" description can also act as a detailed description or can describe a collection of implementation details. Having more than one brief or detailed description is allowed (but not recommended, as the order in which the descriptions will appear is not specified).Īs the name suggest, a brief description is a short one-liner, whereas the detailed description provides longer, more detailed documentation. For methods and functions there is also a third type of description, the so called "in body" description, which consists of the concatenation of all comment blocks found within the body of the method or function. For Python, VHDL, Fortran, and Tcl code there are different comment conventions, which can be found in sections Special documentation blocks in Python, Special documentation blocks in VHDL, Special documentation blocks in Fortran, and Documentation blocks in Tcl respectively.įor each code item there are two (or in some cases three) types of descriptions, which together form the documentation: a brief description and detailed description, both are optional. A special documentation block is a C or C++ style comment block with some additional markings, so doxygen knows it is a piece of documentation that needs to end up in the generated documentation.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |