docs/style/DOXYGEN.adoc

   1 [.text-center]
   2 = Project Connected Home over IP Software
   3
   4 :plusplus: ++
   5
   6 == Doxygen Best Practices, Conventions, and Style
   7
   8 === Comments
   9
  10 Due to Project CHIP’s infrastructure nature, it will be consumed by
  11 other teams, both inside and outside Project CHIP. Therefore it is
  12 critical that how it works, how it behaves, and how it is
  13 interfaced with are **clearly** documented.
  14
  15 In support of this effort Project CHIP uses
  16 http://www.doxygen.org/[Doxygen] to
  17 markup (or markdown) all C, C{plusplus}, Objective C, Objective C{plusplus}, Perl,
  18 Python, and Java code to:
  19
  20 * Detail what the various source and header files are and how they fit
  21 into the broader context.
  22 * Detail what the various C{plusplus} / Objective C{plusplus} namespaces are.
  23 * Detail what the constants, C preprocessor definitions, and
  24 enumerations are.
  25 * Detail what the globals are and how they are to be used.
  26 * Detail what the free function and object / class methods are and how
  27 they are to be used, what their parameters are, and what their return
  28 values are.
  29 * Detail any other important technical information or theory of
  30 operation unique and relevant to the stack that is not otherwise
  31 captured in architecture, design, or protocol documentation.
  32
  33 ==== File
  34
  35 Every C, C{plusplus}, Objective C, Objective C{plusplus}, Perl, Python, Shell, and Java
  36 source file should, at minimum, have a standard, boilerplate Project
  37 CHIP file header that also describes what the file is and how, if
  38 applicable, it fits into the broader implementation.
  39
  40 Canonical examples for C, C{plusplus}, Objective C, and Objective C{plusplus} and
  41 Python, Perl, and shell are shown in Listing 1 and Listing 2 below.
  42
  43 [source,C]
  44 ----
  45 /*
  46  *    Copyright (c) <Create year>[-<Last modified year>] Project CHIP Authors.
  47  *
  48  *    Licensed under the Apache License, Version 2.0 (the "License");
  49  *    you may not use this file except in compliance with the License.
  50  *    You may obtain a copy of the License at
  51  *
  52  *        http://www.apache.org/licenses/LICENSE-2.0
  53  *
  54  *    Unless required by applicable law or agreed to in writing, software
  55  *    distributed under the License is distributed on an "AS IS" BASIS,
  56  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  57  *    See the License for the specific language governing permissions and
  58  *    limitations under the License.
  59  */
  60
  61 /**
  62  *    @file
  63  *        <Brief description>
  64  *
  65  *      [<Detailed description>]
  66  */
  67 ----
  68 [.text-center]
  69 *Listing 1.* Standard, boilerplate Project CHIP file header for C, C{plusplus},
  70 Objective C, and Objective C{plusplus}..
  71
  72 [source,perl]
  73 ----
  74 #
  75 #    Copyright (c) <Create year>[-<Last modified year>] Project CHIP Authors.
  76 #
  77 #    Licensed under the Apache License, Version 2.0 (the "License");
  78 #    you may not use this file except in compliance with the License.
  79 #    You may obtain a copy of the License at
  80 #
  81 #        http://www.apache.org/licenses/LICENSE-2.0
  82 #
  83 #    Unless required by applicable law or agreed to in writing, software
  84 #    distributed under the License is distributed on an "AS IS" BASIS,
  85 #    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  86 #    See the License for the specific language governing permissions and
  87 #    limitations under the License.
  88 #
  89
  90 ##
  91 #    @file
  92 #        <Brief description>
  93 #
  94 #      [<Detailed description>]
  95 #
  96 ----
  97 [.text-center]
  98 *Listing 2.* Standard, boilerplate Project CHIP file header for Perl,
  99 Python, shell, and make.
 100
 101 where:
 102
 103 * _<Create year>_ is the year the file was created.
 104 * _<Last modified year>_ is, optionally, the year the file was last
 105 modified if it is different from _<Create year>_.
 106 * _<Brief description>_ is a succinct description of what the file is.
 107 * _<Detailed description>_ is, optionally, a more in-depth description of
 108 what the file is and how it fits into the broader context.
 109
 110 For header files, a good prologue for _<Brief description>_ is "This file
 111 defines...", describing what is being defined or declared. Likewise, for
 112 source files, a good prologue for _<Brief description>_ is "This file
 113 implements...", describing what is being implemented. Usually,
 114 copy-and-pasting the brief description from the header to the source and
 115 changing the prologue from "defines" to "implements" is sufficient.
 116
 117 The _<Detailed description>_, if present, could be a link to one or more
 118 of the architecture, design, or protocol specifications or some more in
 119 depth but still succinct information about where the file and what it
 120 defines or implements fit into the broader design or implementation.
 121
 122 ===== Motivation and Rationale
 123
 124 The motivation and rationale for this is not from a legal perspective
 125 and as a consequence is not in opposition to guidance from legal.
 126 However, when Project CHIP provides a substantial amount of code as
 127 reference code and as an SDK to third-parties and other work group member
 128 companies, this makes it very clear—and consistently so—what code belongs
 129 to and is authored by Project CHIP and what is not.
 130
 131 ==== Functions and Methods
 132
 133 Every non-trival or non-default public, and ideally private, free function
 134 and class method should likewise have a prologue comment that:
 135
 136 * Briefly describes what it is and what it does.
 137 * Describes in detail, optionally, what it is and what it does.
 138 * Describes the purpose, function, and influence of each parameter as
 139 well as whether it is an input, an output, or both.
 140 * Describes the return value or values, if present, and the expected range or
 141 constraints of it.
 142
 143 The goal of function and method comments are to not simply echo back to the
 144 reader what is in the API signature but to provide value-added insight. Also,
 145 remember that what may be intuitive and self-evident to you as a domain expert
 146 today may not be to your future self or others who are uninitiated in the domain.
 147 The project's success will be measured by the ease, speed, and breadth of its adoption.
 148 Your comments, alongside examples, will contribute toward this goal. When in doubt,
 149 err on the side of being generous with your comments rather than parsimonious.
 150
 151 An example is shown in Listing 3 below for C, C{plusplus}, Objective C, and
 152 Objective C{plusplus}. Adapt as appropriate for Perl, Python and Shell.
 153
 154 [source,C]
 155 ----
 156 /**
 157  * Parse and attempt to convert a string to a 64-bit unsigned integer,
 158  * applying the appropriate interpretation based on the base parameter.
 159  *
 160  * @param[in]  str     A pointer to a NULL-terminated C string representing
 161  *                     the integer to parse.
 162  * @param[out] output  A reference to storage for a 64-bit unsigned integer
 163  *                     to which the parsed value will be stored on success.
 164  * @param[in]  base    The base according to which the string should be
 165  *                     interpreted and parsed. If 0 or 16, the string may
 166  *                     be hexadecimal and prefixed with "0x". Otherwise, a 0
 167  *                     is implied as 10 unless a leading 0 is encountered in
 168  *                     which 8 is implied.
 169  *
 170  * @retval  0 on success.
 171  * @retval  #EINVAL if the given base contains an unsupported value or if no
 172  *          conversion was performed.
 173  * @retval  #ERANGE if the resulting value was out of range.
 174  */
 175 ----
 176 [.text-center]
 177 *Listing 3.* Standard Doxygen-compatible free function or method comment
 178 for C, C{plusplus}, Objective C, and Objective C{plusplus}.
 179
 180 In addition, developers should well document the bodies of their
 181 functions and methods, describing the overall flow, design intent, error
 182 handling nuances, historical bugs encountered and resolved, and so
 183 forth. While these types of comments do not typically become part of the
 184 external documentation, they are invaluable to future maintainers of the
 185 code.
 186
 187 ==== Other
 188
 189 ===== Dos
 190
 191 * *Do* use the '@' Doxygen markup style rather than the '\' markup style.
 192 * *Do* also consider consulting tips on
 193 http://centerforplainlanguage.org/5-steps-to-plain-language/[Plain
 194 Language] for additional style and tone input.
 195 * *Do* use consistent terminology and lingo.
 196 * *Do* properly paragraph justify and wrap your documentation.
 197
 198 ** See your editor's documentation on how to do this (for example, M-q in Emacs).
 199
 200 ===== Don'ts
 201
 202 * *Do not* forget to document your files, enumerations, constants,
 203 classes, objects, namespaces, functions, and methods.
 204 * *Do not* include the file name in any Doxygen file comments or
 205 directives.
 206
 207 ** Your editor knows the [.underline]#file name#, source code control knows the file
 208 name, and you know the file name.
 209 ** When it changes on the file system, having to change it in the file
 210 comments is simply an added burden.
 211
 212 * *Do not* include [.underline]#your name# in any Doxygen comments or directives.
 213
 214 ** Source code control knows who you are and what file revisions you own.
 215 ** We do not want Project CHIP consumers knowing who you are and calling
 216 or e-mailing you directly for support.
 217
 218 * *Do not* include the [.underline]#modification date# the file was last changed in
 219 Doxygen comments or directives, [.underline]#except for the copyright header#.
 220
 221 ** Source code control knows when the file was last changed and the date
 222 other revisions were made.
 223
 224 * *Do not* include subjective or opinionated commentary or expose
 225 proprietary and confidential information not relevant to the code or
 226 APIs.
 227
 228 ** This content *will be* published to and for consumption by members, the
 229 CHIP community, and the general public.
 230
 231 == Revision History
 232
 233 [cols="^1,^1,<2,<3",options="header"]
 234 |===
 235 |Revision |Date |Modified By |Description
 236 |1 |2020-06-11 |Grant Erickson |Initial revision.
 237 |===
 238
 239 [.text-center]
 240 _Project Connect Home over IP Public Information_