<commit_before>[.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 it works, how it behaves, and how it is
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.<commit_msg>Added Apache v2 license boilerplate to listings.<commit_after>[.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 it works, how it behaves, and how it is
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.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License. 
 */

/**
 *    @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.
#
#    Licensed under the Apache License, Version 2.0 (the "License");
#    you may not use this file except in compliance with the License.
#    You may obtain a copy of the License at
#
#        http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
#

##
#    @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.
{'fraction_non_alphanumeric': 0.08093186102881766, 'fraction_numerical': 0.0022892539725289525, 'mean_word_length': 4.0148548278190415, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3792062', 'n_tokens_mistral': 2114, 'n_tokens_neox': 2023, 'n_words': 1025}