Initial revision.

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) <Create year>[-<Last modified year>] Project CHIP Authors.
+ */
+
+/**
+ *    @file
+ *        <Brief description>
+ *
+ *      [<Detailed description>]
+ */
+----
+[.text-center]
+*Listing 1.* Standard, boilerplate Project CHIP file header for C, C{plusplus},
+Objective C, and Objective C{plusplus}..
+
+[source,perl]
+----
+#
+#    Copyright (c) <Create year>[-<Last modified year>] Project CHIP Authors.
+#
+
+##
+#    @file
+#        <Brief description>
+#
+#      [<Detailed description>]
+#
+----
+[.text-center]
+*Listing 2.* Standard, boilerplate Project CHIP file header for Perl,
+Python, shell, and make.
+
+where:
+
+* _<Create year>_ is the year the file was created.
+* _<Last modified year>_ is, optionally, the year the file was last
+modified if it is different from _<Create year>_.
+* _<Brief description>_ is a succinct description of what the file is.
+* _<Detailed description>_ 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 _<Brief description>_ is "This file
+defines...", describing what is being defined or declared. Likewise, for
+source files, a good prologue for _<Brief description>_ 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 _<Detailed description>_, 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_