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 Doxygen to markup (or markdown) all C, C++, Objective C, Objective C++, 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++ / Objective C++ 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.
Every C, C++, Objective C, Objective C++, 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++, Objective C, and Objective C++ and Python, Perl, and shell are shown in Listing 1 and Listing 2 below.
/*
* Copyright (c) <Create year>[-<Last modified year>] Project CHIP Authors.
*/
/**
* @file
* <Brief description>
*
* [<Detailed description>]
*/Listing 1. Standard, boilerplate Project CHIP file header for C, C++, Objective C, and Objective C++..
#
# Copyright (c) <Create year>[-<Last modified year>] Project CHIP Authors.
#
##
# @file
# <Brief description>
#
# [<Detailed description>]
#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.
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.
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++, Objective C, and Objective C++. Adapt as appropriate for Perl, Python and Shell.
/**
* 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.
*/Listing 3. Standard Doxygen-compatible free function or method comment for C, C++, Objective C, and Objective C++.
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.
-
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 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).
-
-
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 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 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 modification date the file was last changed in Doxygen comments or directives, 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.
-