1/**
2 * Description of the coding style for the source files.
3 *
4 * @file        codingStyle
5 * @ingroup     codingStyle
6 * @author      name
7 * @copyright   2020 name
8 *
9 * Licensed under the Apache License, Version 2.0 (the "License");
10 * you may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 *     http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS,
17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 */
21
22#ifndef XYZ_H
23#define XYZ_H
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29/**
30 * @defgroup codingStyle Description of coding style
31 * @ingroup parentGroup
32 * @{
33 *
34 * Contents of this file should be the base for .h source file, except function
35 * body at the end.
36 *
37 * ###Style
38 *  - Style is based on Linux style
39 *  - Indent size is 4.
40 *  - Spaces are used, not tabs.
41 *  - More datails are defined in .clang-format file
42 *  - Some (old) code is still not corectly formatted. (To not break git history.)
43 *
44 * ###Doxygen
45 * Documentation is generated by doxygen.
46 * Doxygen comment starts with /**. /**< is used after member.
47 * Documentation is usually in header.
48 * Doxygen settings:
49 *  - JAVADOC_AUTOBRIEF = YES.
50 *  - See doxyfile for other settings.
51 *
52 * Doxygen specifics: If description of the structure member is one sentence
53 * only, don't use period after the sentence.
54 *
55 * ###Misra C
56 * Code shall follow MISRA-C:2012 standard.
57 */
58
59
60/**
61 * Brief description of the object ends at this dot. Details follow
62 * here.
63 */
64typedef struct {
65    int8_t member1;   /**< Short description of the member 1 */
66    uint16_t member2; /**< Note the '/**<' sequence after the member 2 */
67    /** Long description of the variable stringMember. More description. */
68    char_t stringMember[5];
69} object1_t;
70
71
72/**
73 * Function example 1.
74 *
75 * This is global function. Local functions (and variables) used inside one file
76 * are declared as static and not documented by Doxygen.
77 *
78 * @param obj Pointer to object. Function operates on this object (not on global
79 * variables).
80 * @param argument_2 Description of the argument.
81 * @param argument_2 Description of the argument.
82 * @param argument_4 Description of the argument.
83 *
84 * @return Some value.
85 */
86int32_t foo1(object1_t *obj,
87             int32_t argument_2,
88             uint16_t argument_3,
89             float32_t argument_4)
90{
91    /* Comment */
92
93    /* Multiline
94     * comment.
95     */
96
97    if (xy == yz) { /* Comment. '//' comments are not allowed */
98        a = b;
99    } else {
100        a = c;
101    }
102
103    switch (zx) {
104    case 1:
105        a = b;
106        break;
107    }
108}
109
110/** @} */
111
112#ifdef __cplusplus
113}
114#endif /*__cplusplus */
115
116#endif /* XYZ_H */
117