Mercurial > molko

annotate STYLE.md @ 13:c188e9603faf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: add basic documentation files
author David Demelier <markand@malikania.fr>
date Tue, 07 Jan 2020 21:34:03 +0100
parents
children 98e091b9251e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
13
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 Molko's Adventure CODING STYLE
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 ==============================
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
3
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 File content
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 ============
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
6
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 - Use UTF-8 charset,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 - Use Unix line endings,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 - Never write two consecutives blank lines.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
10
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 Indent
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 ======
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
13
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 Use tabs to indent and spaces for alignment. Tabs are meant and designed for
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 indenting code and have the advantage of being configurable. On the other hand
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 to keep code clean, you must align content with spaces only *within* a line.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
17
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 Note: we recommend 8 columns to avoid high number of indentations.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
19
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 Example (show whitespace in your editor)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 ```cpp
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 class foo {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 public:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 enum type {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 dummy_value, // dummy comment
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 other_value // other comment
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 };
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
29
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 void long_function_name(very_long_type x1,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 very_long_type x2)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 const map<string, string> m{
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
34 { "hostname", "127.0.0.1" },
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 { "port", "6667" }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 };
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 };
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
40
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 As a rule of thumb, tabs must always be all length.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
42
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 Example of incorrect usage:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
44
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 ```cpp
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 { "hostname", "127.0.0.1" },
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 { "port", "6667" }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
49
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 This example will not align correctly if tabstops are not set to 8.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
51
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 C
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 =
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
54
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 Style
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 -----
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
57
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 - Do not exceed 80 columns.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
59
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 ### Braces
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
61
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 Braces follow the K&R style, they are never placed on their own lines except for
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 function definitions.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
64
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 Do not put braces for single line statements.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
66
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 if (condition) {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 apply();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 add();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 } else
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 ok();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
73
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 if (condition)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 validate();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
76
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 if (foo)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 state = long + conditional + that + requires + several + lines +
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 to + complete;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
81
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 Functions require braces on their own lines.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
83
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
84 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 void
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 function()
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
90
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 Note: the type of a function is broken into its own line.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
92
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
93 ### Spaces
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
94
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
95 Each reserved keyword (e.g. `if`, `for`, `while`) requires a single space before
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 its argument.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
97
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
98 Normal function calls do not require it.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
99
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
100 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 if (foo)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
102 destroy(sizeof (int));
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
104
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 ### Pointers
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
106
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
107 Pointers are always next variable name.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
108
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
109 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 void
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 cleanup(struct owner *owner);
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
112 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
113
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
114 ### Typedefs
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
115
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
116 Do not use typedef for non-opaque objects. It is allowed for function pointers.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
117
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
118 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
119 struct pack {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
120 int x;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
121 int y;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
122 };
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
123
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
124 typedef void (*logger)(const char *line);
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
125 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
126
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 Note: do never add `_t` suffix to typedef's.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
128
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
129 ### Naming
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
130
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
131 - English names,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 - No hungarian notation,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
133
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
134 Almost everything is in `underscore_case` except macros and enumeration
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
135 constants.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
136
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
137 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
138 #if defined(FOO)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
139 # include <foo.hpp>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
140 #endif
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
141
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
142 #define MAJOR 1
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
143 #define MINOR 0
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
144 #define PATCH 0
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
145
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
146 enum color {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
147 COLOR_RED,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
148 COLOR_GREEN,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
149 COLOR_BLUE
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
150 };
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
151
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
152 void
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
153 add_widget(const struct widget *widget_to_add);
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
154 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
155
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
156 ### Header guards
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
157
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
158 Do not use `#pragma once`.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
159
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
160 Header guards are usually named `PROJECT_COMPONENT_FILENAME_H`.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
161
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
162 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
163 #ifndef FOO_COMMON_UTIL_H
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
164 #define FOO_COMMON_UTIL_H
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
165
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
166 #endif /* !FOO_COMMON_UTIL_HPP */
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
167 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
168
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
169 ### Enums
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
170
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
171 Enumerations constants are always defined in separate line to allow commenting
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
172 them as doxygen.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
173
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
174 Note: enumeration constants are prefixed with its name.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
175
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
176 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
177 enum color {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
178 COLOR_RED,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
179 COLOR_GREEN,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
180 COLOR_BLUE
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
181 };
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
182 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
183
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
184 ### Switch
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
185
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
186 In a switch case statement, you **must** not declare variables and not indent
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
187 cases.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
188
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
189 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
190 switch (variable) {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
191 case foo:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
192 do_some_stuff();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
193 break;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
194 default:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
195 break;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
196 }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
197 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
198
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
199 ### Files
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
200
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
201 - Use `.c` and `.h` as file extensions,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
202 - Filenames are all lowercase.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
203
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
204 ### Comments
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
205
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
206 Avoid useless comments in source files. Comment complex things or why it is done
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
207 like this. However any public function in the .h **must** be documented as
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
208 doxygen without exception.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
209
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
210 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
211 /*
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
212 * Multi line comments look like
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
213 * this.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
214 */
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
215
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
216 // Short comment
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
217 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
218
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
219 Use `#if 0` to comment blocks of code.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
220
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
221 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
222 #if 0
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
223 broken_stuff();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
224 #endif
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
225 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
226
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
227 ### Includes
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
228
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
229 The includes should always come in the following order.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
230
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
231 1. System headers (POSIX mostly)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
232 2. C header
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
233 3. Third party libraries
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
234 4. Application headers in ""
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
235
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
236 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
237 #include <sys/types.h>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
238 #include <sys/stat.h>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
239 #include <string.h>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
240
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
241 #include <libircclient.h>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
242
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
243 #include "foo.h"
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
244 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
245
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
246 Programming
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
247 -----------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
248
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
249 ### C Standard
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
250
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
251 Use C99 standard without extensions.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
252
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
253 ### Assertions
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
254
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
255 Use the `assert` macro from the assert.h header file to verify programming
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
256 errors.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
257
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
258 For example, you may use `assert` to verify that the developer access the data
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
259 between the bounds of an array:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
260
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
261 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
262 int
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
263 get(struct data *data, unsigned index)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
264 {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
265 assert(index < data->length);
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
266
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
267 return data->buffer[index];
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
268 }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
269 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
270
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
271 The `assert` macro is not meant to check that a function succeeded, this code
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
272 must not be written that way:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
273
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
274 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
275 assert(listen(10));
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
276 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
277
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
278 ### Return
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
279
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
280 The preferred style is to return early in case of errors. That makes the code
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
281 more linear and not highly indented.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
282
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
283 This code is preferred:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
284
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
285 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
286 if (a_condition_is_not_valid)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
287 return false;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
288 if (an_other_condition)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
289 return false;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
290
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
291 start();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
292 save();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
293
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
294 return true;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
295 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
296
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
297 Additional rules:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
298
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
299 - Do never put parentheses between the returned value,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
300 - Do not put a else branch after a return.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
301
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
302 Shell
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
303 =====
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
304
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
305 Write POSIX shell only with no bash, zsh or any extension.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
306
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
307 Style
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
308 -----
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
309
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
310 - Try to keep lines shorter than 80 columns
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
311
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
312 Functions
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
313 ---------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
314
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
315 Don't use `function` keyword, just keep the function name.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
316
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
317 ```sh
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
318 usage()
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
319 {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
320 }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
321 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
322
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
323 It's usually recommended to prefix functions names with the program name to
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
324 avoid collisions with global commands.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
325
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
326 ```sh
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
327 foo_clean()
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
328 {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
329 }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
330
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
331 foo_process()
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
332 {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
333 }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
334 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
335
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
336 Options
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
337 -------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
338
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
339 For options, use `getopts` and prefer short options to long unless necessary.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
340 Also set OPTERR=0 to avoid printing errors and do it yourself for UX
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
341 consistency.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
342
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
343 ```sh
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
344 OPTERR=0
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
345 while getopts "v" arg; do
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
346 case $arg in
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
347 v)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
348 verbose=1
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
349 ;;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
350 esac
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
351 done
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
352 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
353
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
354 Naming
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
355 ------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
356
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
357 Use `UPPERCASE` variables for global variables and `lowercase` for temporary or
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
358 local variables.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
359
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
360 Markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
361 ========
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
362
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
363 Headers
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
364 -------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
365
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
366 For 1st and 2nd level headers, use `===` and `---` delimiters and underline the
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
367 whole title. Otherwise use `###`.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
368
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
369 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
370 Top level title
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
371 ===============
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
372
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
373 Sub title
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
374 ---------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
375
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
376 ### Header 3
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
377
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
378 #### Header 4
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
379
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
380 ##### Header 5
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
381
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
382 ###### Header 6
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
383 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
384
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
385 Lists
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
386 -----
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
387
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
388 Use hyphens for unordered lists for consistency, do not indent top level lists,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
389 then indent by two spaces each level
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
390
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
391 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
392 - unordered list 1
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
393 - unordered list 2
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
394 - sub unordered item
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
395
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
396 1. unordered list 1
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
397 2. unordered list 2
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
398 2.1. sub unordered item
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
399 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
400
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
401 Code blocks
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
402 -----------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
403
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
404 You can use three backticks and the language specifier or just indent a block by
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
405 for leading spaces if you don't need syntax.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
406
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
407 ```cpp
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
408 std::cout << "hello world" << std::endl;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
409 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
410
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
411 And without syntax:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
412
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
413 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
414 This is simple code block.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
415 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
416
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
417 Tables
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
418 ------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
419
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
420 Tables are supported and formatted as following:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
421
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
422 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
423 | header 1 | header 2 |
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
424 |----------|----------|
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
425 | item 1 | item 2 |
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
426 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
427
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
428 Alerts
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
429 ------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
430
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
431 It's possible to prefix a paragraph by one of the following topic, it renders a
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
432 different block depending on the output format:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
433
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
434 - Note:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
435 - Warning:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
436 - Danger:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
437
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
438 Then, if the paragraph is too long, indent the text correctly.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
439
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
440 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
441 Note: this is an information block that is too long to fit between the limits so
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
442 it is split and indented.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
443 ```