From ff25bf8c66fb13f507180eafced6f9dbfacdf1f9 Mon Sep 17 00:00:00 2001 From: Grant Erickson Date: Thu, 28 May 2020 13:40:34 -0700 Subject: [PATCH] Initial revision. --- docs/style/DOXYGEN.adoc | 206 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 docs/style/DOXYGEN.adoc diff --git a/docs/style/DOXYGEN.adoc b/docs/style/DOXYGEN.adoc new file mode 100644 index 00000000000000..657ddc034de9d1 --- /dev/null +++ b/docs/style/DOXYGEN.adoc @@ -0,0 +1,206 @@ +[.text-center] += Project Connected Home over IP Software + +:plusplus: ++ + +== Doxygen Best Practices, Conventions, and Style + +=== Comments + +Due to Project CHIP’s infrastructure nature, it will be consumed by +other teams, both inside and outside Project CHIP. Therefore it is +critical that how they work, how they behave, and how they are +interfaced with are clearly documented. + +In support of this effort Project CHIP uses +http://www.doxygen.org/[Doxygen] to +markup (or markdown) all C, C{plusplus}, Objective C, Objective C{plusplus}, Perl, +Python, and Java code to: + +* Detail what the various source and header files are and how they fit +into the broader context. +* Detail what the various C{plusplus} / Objective C{plusplus} namespaces are. +* Detail what the constants, C preprocessor definitions, and +enumerations are. +* Detail what the globals are and how they are to be used. +* Detail what the free function and object / class methods are and how +they are to be used, what their parameters are, and what their return +values are. +* Detail any other important technical information or theory of +operation unique and relevant to the stack that is not otherwise +captured in architecture, design, or protocol documentation. + +==== File + +Every C, C{plusplus}, Objective C, Objective C{plusplus}, Perl, Python, Shell, and Java +source file should, at minimum, have a standard, boilerplate Project +CHIP file header that also describes what the file is and how, if +applicable, it fits into the broader implementation. + +Canonical examples for C, C{plusplus}, Objective C, and Objective C{plusplus} and +Python, Perl, and shell are shown in Listing 1 and Listing 2 below. + +[source,C] +---- +/* + * Copyright (c) [-] Project CHIP Authors. + */ + +/** + * @file + * + * + * [] + */ +---- +[.text-center] +*Listing 1.* Standard, boilerplate Project CHIP file header for C, C{plusplus}, +Objective C, and Objective C{plusplus}.. + +[source,perl] +---- +# +# Copyright (c) [-] Project CHIP Authors. +# + +## +# @file +# +# +# [] +# +---- +[.text-center] +*Listing 2.* Standard, boilerplate Project CHIP file header for Perl, +Python, shell, and make. + +where: + +* __ is the year the file was created. +* __ is, optionally, the year the file was last +modified if it is different from __. +* __ is a succinct description of what the file is. +* __ is, optionally, a more in-depth description of +what the file is and how it fits into the broader context. + +For header files, a good prologue for __ is "This file +defines...", describing what is being defined or declared. Likewise, for +source files, a good prologue for __ is "This file +implements...", describing what is being implemented. Usually, +copy-and-pasting the brief description from the header to the source and +changing the prologue from "defines" to "implements" is sufficient. + +The __, if present, could be a link to one or more +of the architecture, design, or protocol specifications or some more in +depth but still succinct information about where the file and what it +defines or implements fit into the broader design or implementation. + +===== Motivation and Rationale + +The motivation and rationale for this is not from a legal perspective +and as a consequence is not in opposition to guidance from legal. +However, when Project CHIP provides a substantial amount of code as +reference code and as an SDK to third-parties and other work group member +companies, this makes it very clear—and consistently so—what code belongs +to and is authored by Project CHIP and what is not. + +==== Functions and Methods + +Every public, and ideally private, free function and class method should +likewise have a prologue comment that: + +* Briefly describes what it is and what it does. +* Describes in detail, optionally, what it is and what it does. +* Describes the purpose, function, and influence of each parameter as +well as whether it is an input, an output, or both. +* Describes the return value, if present, and the expected range or +constraints of it. + +An example is shown in Listing 3 below for C, C{plusplus}, Objective C, and +Objective C{plusplus}. Adapt as appropriate for Perl, Python and Shell. + +[source,C] +---- +/** + * Parse and attempt to convert a string to a 64-bit unsigned integer, + * applying the appropriate interpretation based on the base parameter. + * + * @param[in] str A pointer to a NULL-terminated C string representing + * the integer to parse. + * @param[out] output A reference to storage for a 64-bit unsigned integer + * to which the parsed value will be stored on success. + * @param[in] base The base according to which the string should be + * interpreted and parsed. If 0 or 16, the string may + * be hexadecimal and prefixed with "0x". Otherwise, a 0 + * is implied as 10 unless a leading 0 is encountered in + * which 8 is implied. + * + * @return true on success; otherwise, false on failure. + */ +---- +[.text-center] +*Listing 3.* Standard Doxygen-compatible free function or method comment +for C, C{plusplus}, Objective C, and Objective C{plusplus}. + +In addition, developers should well document the bodies of their +functions and methods, describing the overall flow, design intent, error +handling nuances, historical bugs encountered and resolved, and so +forth. While these types of comments do not typically become part of the +external documentation, they are invaluable to future maintainers of the +code. + +==== Other + +===== Dos + +* *Do* use the '@' Doxygen markup style rather than the '\' markup style. +uncomfortable or unclear on your own writing style. +* *Do* also consider consulting tips on +http://centerforplainlanguage.org/5-steps-to-plain-language/[Plain +Language] for additional style and tone input. +* *Do* use consistent terminology and lingo. +* *Do* properly paragraph justify and wrap your documentation. + +** See your editor's documentation on how to do this (for example, M-q in Emacs). + +===== Don'ts + +* *Do not* forget to document your files, enumerations, constants, +classes, objects, namespaces, functions, and methods. +* *Do not* include the file name in any Doxygen file comments or +directives. + +** Your editor knows the [.underline]#file name#, source code control knows the file +name, and you know the file name. +** When it changes on the file system, having to change it in the file +comments is simply an added burden. + +* *Do not* include [.underline]#your name# in any Doxygen comments or directives. + +** Source code control knows who you are and what file revisions you own. +** We do not want Project CHIP consumers knowing who you are and calling +or e-mailing you directly for support. + +* *Do not* include the [.underline]#modification date# the file was last changed in +Doxygen comments or directives, [.underline]#except for the copyright header#. + +** Source code control knows when the file was last changed and the date +other revisions were made. + +* *Do not* include subjective or opinionated commentary or expose +proprietary and confidential information not relevant to the code or +APIs. + +** This content *will be* published to and for consumption by members, the +CHIP community, and the general public. + +== Revision History + +[cols="^1,^1,<2,<3",options="header"] +|=== +|Revision |Date |Modified By |Description +|1 |2020-05-28 |Grant Erickson |Initial revision. +|=== + +[.text-center] +_Project Connect Home over IP Public Information_