Guidelines for API documentation » History » Version 25
osmith, 03/23/2021 02:45 PM
change [inout] to [in,out], so it's the same in both examples. doxygen makes "in,out" from both versions in the HTML docs, but IMHO "in,out" is more readable "inout". by only having one version here in the guidelines, there is no confusion.
| 1 | 1 | neels | h1. Guidelines for API documentation |
|---|---|---|---|
| 2 | |||
| 3 | 12 | neels | Find the current API doc in HTML form here: http://ftp.osmocom.org/api/latest/ |
| 4 | |||
| 5 | 13 | neels | We use doxygen for API documentation, for an overview see http://www.doxygen.nl/manual/docblocks.html. Please follow these guidelines: |
| 6 | 1 | neels | |
| 7 | 14 | neels | h2. Marker style |
| 8 | |||
| 9 | 1 | neels | Use the @/*!@ (Qt-style) doxygen markers. |
| 10 | 14 | neels | <pre> |
| 11 | /*! Item summary. |
||
| 12 | * Details follow. */ |
||
| 13 | struct item { |
||
| 14 | int member; /*!< Member summary. */ |
||
| 15 | }; |
||
| 16 | </pre> |
||
| 17 | 1 | neels | |
| 18 | 14 | neels | h2. Summary |
| 19 | |||
| 20 | Since we are using the AUTOBRIEF feature, omit '\brief', and always end the first sentence with a full-stop "." to mark the end of the short description. |
||
| 21 | |||
| 22 | To have a dot in a summary, use an escaped space like |
||
| 23 | 1 | neels | <pre>/*! Brief description (e.g.\ using only a few words). Details follow. */</pre> |
| 24 | |||
| 25 | Never rely on line breaks as semantic separation or to end a sentence, always use proper punctuation. The API doc may be rendered with different line breaks than in the source file. |
||
| 26 | 4 | neels | |
| 27 | h2. Locations |
||
| 28 | |||
| 29 | Header files usually contain merely function declarations bare of any API docs. The API doc comment should be in a @.c@ file at the definition of a function. |
||
| 30 | |||
| 31 | Structs and enums defined in a header file, though, also have their API doc comments in that @.h@ file. |
||
| 32 | 10 | neels | |
| 33 | Comments for single-line items like enum values or struct members can be placed on the same line using @/*!< Description */@. |
||
| 34 | 4 | neels | |
| 35 | h2. Grammar |
||
| 36 | |||
| 37 | Always use the imperative form, i.e. omit wording like "This function does", and avoid writing documentation that merely mirrors a function's name. For example: |
||
| 38 | |||
| 39 | <pre> |
||
| 40 | /*! Return a (static) buffer containing a hexdump of the msg. |
||
| 41 | * \param[in] msg message buffer |
||
| 42 | 15 | neels | * \return a pointer to a static char array |
| 43 | 4 | neels | */ |
| 44 | const char *msgb_hexdump(const struct msgb *msg) |
||
| 45 | { |
||
| 46 | ... |
||
| 47 | </pre> |
||
| 48 | |||
| 49 | 1 | neels | h2. Parameters |
| 50 | 12 | neels | |
| 51 | 4 | neels | All parameters of a function should be documented. Input params are documented with @\param[in]@, where out-parameters (pointers to which returned data is written) are documented with @\param[out]@. Rarely, a param is both: @\param[in,out]@. |
| 52 | |||
| 53 | <pre> |
||
| 54 | /*! Apply nifty algorithm. |
||
| 55 | * \param[in] x0 First factor. |
||
| 56 | * \param[in] n Amount of values to calculate. |
||
| 57 | * \param[out] buf Write calculated values to this buffer. |
||
| 58 | * |
||
| 59 | 1 | neels | * Optional longer function description. */ |
| 60 | 7 | neels | </pre> |
| 61 | 8 | neels | |
| 62 | 25 | osmith | It is also possible to document parameters without a direction, using merely @\param param_name Description@, however, it is desirable to always indicate @[in]@, @[out]@ or @[in,out]@. |
| 63 | 1 | neels | |
| 64 | 16 | osmith | Parameters can *not* be referenced with @\ref@, nor with @\a@. See "this post":https://lists.osmocom.org/pipermail/openbsc/2019-January/012603.html for details. |
| 65 | |||
| 66 | 19 | neels | h2. Files and Groups |
| 67 | 1 | neels | |
| 68 | 24 | neels | Choose distinct names in the '\file' and '\defgroup' directives: similar names will confuse Doxygen, even if they are in separate subdirs and even separate libraries. |
| 69 | 17 | neels | An example is osmocom/code/stats.h vs osmocom/vty/stats.h. If both of these are advertised as '\file stats.h', the duplicate handle will lead to both files missing from their respective groups. |
| 70 | 11 | neels | Solutions: |
| 71 | 9 | neels | |
| 72 | 19 | neels | * write '\file core/stats.h' and '\file vty/stats.h'. |
| 73 | * do not use identical file or group names in the first place. |
||
| 74 | 1 | neels | |
| 75 | 18 | neels | Doxygen allows grouping elements: a group can include code elements and also entire files, and join them with a common description and cross references. |
| 76 | 1 | neels | |
| 77 | 18 | neels | Use this pattern: |
| 78 | 1 | neels | |
| 79 | <pre> |
||
| 80 | 18 | neels | /*! \file foo.h |
| 81 | * API to provide Fooing. |
||
| 82 | 1 | neels | */ |
| 83 | 18 | neels | /* Copyright... |
| 84 | */ |
||
| 85 | 1 | neels | |
| 86 | 18 | neels | #include <xyz> |
| 87 | 1 | neels | |
| 88 | 18 | neels | /*! \defgroup fooing Fooing Listed Name |
| 89 | 1 | neels | * @{ |
| 90 | 18 | neels | * \file foo.h |
| 91 | 1 | neels | */ |
| 92 | |||
| 93 | 18 | neels | struct foo { |
| 94 | 1 | neels | ... |
| 95 | 18 | neels | }; |
| 96 | 1 | neels | |
| 97 | 18 | neels | int foo(struct foo *f); |
| 98 | |||
| 99 | 1 | neels | /*! @} */ |
| 100 | </pre> |
||
| 101 | |||
| 102 | <pre> |
||
| 103 | /*! \file foo.c |
||
| 104 | 18 | neels | * Implementation of Fooing. |
| 105 | 1 | neels | */ |
| 106 | 18 | neels | /* Copyright... |
| 107 | 1 | neels | */ |
| 108 | |||
| 109 | 18 | neels | /*! \addtogroup fooing |
| 110 | 1 | neels | * |
| 111 | 18 | neels | * Fooing short description of one sentence. |
| 112 | 1 | neels | * |
| 113 | 18 | neels | * Fooing has a long description with many applications in modern Foo science. |
| 114 | * Apply the Foo, not to be confused with the Fu, or Kung. |
||
| 115 | 6 | neels | * |
| 116 | 18 | neels | * @{ |
| 117 | * \file foo.c |
||
| 118 | 1 | neels | */ |
| 119 | |||
| 120 | 18 | neels | int foo(struct foo *f) { |
| 121 | return 0xf00; |
||
| 122 | } |
||
| 123 | 1 | neels | |
| 124 | ... |
||
| 125 | |||
| 126 | 18 | neels | /*! @} */ |
| 127 | 1 | neels | </pre> |
| 128 | 18 | neels | |
| 129 | 20 | neels | You can reference this group across libraries, for example: |
| 130 | |||
| 131 | <pre> |
||
| 132 | /*! \defgroup fooing_vty |
||
| 133 | * VTY for \ref fooing. |
||
| 134 | */ |
||
| 135 | </pre> |
||
| 136 | |||
| 137 | 21 | neels | Which will render as "VTY for Fooing Listed Name." |
| 138 | (if cross referencing is set up properly, here between the core and vty libraries). |
||
| 139 | 20 | neels | |
| 140 | Reasons for above pattern: |
||
| 141 | 18 | neels | |
| 142 | * A \file with short description should be the first line of the file. |
||
| 143 | * Later on, name the same \file without the short description, after an opening @{ to add to a specific group. |
||
| 144 | * Do not add other #include directives within the group braces. |
||
| 145 | * A \defgroup initially defines a group, this shall exist only once, preferably in a .h file. |
||
| 146 | * More items can be added using an \addtogroup marker. Use this in the .c file and add a long description with references. |
||
| 147 | * Put the longer description in the .c file, not the .h file. |
||
| 148 | 23 | neels | * Items enclosed in "@@{" and "@@}" are added to a group. Make sure to remember closing the brace. |
| 149 | 18 | neels | * Choose distinct group and file names, even across separate libraries, e.g. "\defgroup foo" and "\defgroup foo_VTY", |
| 150 | or "\file foo.h" and "\file vty/foo.h". |
||
| 151 | * Be aware, any description following \file will be associated with that file and not the group. |
||
| 152 | * If a file's description matches a group's description, don't describe the file at all to avoid duplicated docs. |
