Mercurial > molko

annotate STYLE.md @ 217:836bac1419c7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
examples: improve map example
author David Demelier <markand@malikania.fr>
date Wed, 18 Nov 2020 10:13:29 +0100
parents 98e091b9251e
children 19782ea1cf4a
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 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
21
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 Example of incorrect usage:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
23
15
98e091b9251e misc: update STYLE.md
David Demelier <markand@malikania.fr>
parents: 13
diff changeset
24 ```c
13
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 { "hostname", "127.0.0.1" },
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 { "port", "6667" }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 ```
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 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
30
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 C
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
34 Style
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 -----
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 - Do not exceed 80 columns.
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 ### Braces
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 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
42 function definitions.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
43
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
44 Do not put braces for single line statements.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
45
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 if (condition) {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 apply();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 add();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 } else
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 ok();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
52
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 if (condition)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 validate();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
55
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 if (foo)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 state = long + conditional + that + requires + several + lines +
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 to + complete;
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 Functions require braces on their own lines.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
62
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 void
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 function()
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 }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
69
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 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
71
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 ### Spaces
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 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
75 its argument.
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 Normal function calls do not require it.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
78
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 if (foo)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 destroy(sizeof (int));
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 ```
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 ### Pointers
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
85
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 Pointers are always next variable name.
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 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 void
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 cleanup(struct owner *owner);
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 ```
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 ### Typedefs
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 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
96
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
98 struct pack {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 int x;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
100 int y;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 };
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
102
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 typedef void (*logger)(const char *line);
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 Note: do never add `_t` suffix to typedef's.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
107
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
108 ### Naming
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
109
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 - English names,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 - No hungarian notation,
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 Almost everything is in `underscore_case` except macros and enumeration
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
114 constants.
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 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 #if defined(FOO)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
118 # include <foo.hpp>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
119 #endif
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
120
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
121 #define MAJOR 1
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
122 #define MINOR 0
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
123 #define PATCH 0
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
124
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
125 enum color {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
126 COLOR_RED,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 COLOR_GREEN,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
128 COLOR_BLUE
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
129 };
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 void
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 add_widget(const struct widget *widget_to_add);
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
135 ### Header guards
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 Do not use `#pragma once`.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
138
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
139 Header guards are usually named `PROJECT_COMPONENT_FILENAME_H`.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
140
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
141 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
142 #ifndef FOO_COMMON_UTIL_H
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
143 #define FOO_COMMON_UTIL_H
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
144
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
145 #endif /* !FOO_COMMON_UTIL_HPP */
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
146 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
147
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
148 ### Enums
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
149
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
150 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
151 them as doxygen.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
152
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
153 Note: enumeration constants are prefixed with its name.
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 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
156 enum color {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
157 COLOR_RED,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
158 COLOR_GREEN,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
159 COLOR_BLUE
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
160 };
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
163 ### Switch
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
164
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
165 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
166 cases.
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 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
169 switch (variable) {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
170 case foo:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
171 do_some_stuff();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
172 break;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
173 default:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
174 break;
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 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
177
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
178 ### Files
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
179
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
180 - Use `.c` and `.h` as file extensions,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
181 - Filenames are all lowercase.
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 ### Comments
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
184
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
185 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
186 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
187 doxygen without exception.
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 /*
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
191 * Multi line comments look like
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
192 * this.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
193 */
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
194
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
195 // Short comment
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 Use `#if 0` to comment blocks of code.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
199
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
200 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
201 #if 0
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
202 broken_stuff();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
203 #endif
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
204 ```
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 ### Includes
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
207
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
208 The includes should always come in the following order.
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 1. System headers (POSIX mostly)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
211 2. C header
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
212 3. Third party libraries
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
213 4. Application headers in ""
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 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
216 #include <sys/types.h>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
217 #include <sys/stat.h>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
218 #include <string.h>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
219
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
220 #include <libircclient.h>
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
221
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
222 #include "foo.h"
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
223 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
224
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
225 Programming
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
228 ### C Standard
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
229
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
230 Use C99 standard without extensions.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
231
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
232 ### Assertions
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
233
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
234 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
235 errors.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
236
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
237 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
238 between the bounds of an array:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
239
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
240 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
241 int
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
242 get(struct data *data, unsigned index)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
243 {
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
244 assert(index < data->length);
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 return data->buffer[index];
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
250 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
251 must not be written that way:
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 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
254 assert(listen(10));
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
255 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
256
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
257 ### Return
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
258
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
259 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
260 more linear and not highly indented.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
261
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
262 This code is preferred:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
263
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
264 ```c
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
265 if (a_condition_is_not_valid)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
266 return false;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
267 if (an_other_condition)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
268 return false;
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 start();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
271 save();
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
272
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
273 return true;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
274 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
275
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
276 Additional rules:
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 - Do never put parentheses between the returned value,
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
279 - Do not put a else branch after a return.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
280
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
281 Shell
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
284 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
285
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
286 Style
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
287 -----
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
288
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
289 - Try to keep lines shorter than 80 columns
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 Functions
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
292 ---------
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 Don't use `function` keyword, just keep the function name.
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 ```sh
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
297 usage()
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 }
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
300 ```
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 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
303 avoid collisions with global commands.
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 ```sh
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
306 foo_clean()
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
307 {
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 foo_process()
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 }
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 Options
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
318 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
319 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
320 consistency.
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 ```sh
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
323 OPTERR=0
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
324 while getopts "v" arg; do
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
325 case $arg in
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
326 v)
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
327 verbose=1
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 esac
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
330 done
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
331 ```
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 Naming
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 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
337 local variables.
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 Markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
340 ========
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
341
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
342 Headers
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
343 -------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
344
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
345 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
346 whole title. Otherwise use `###`.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
347
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
348 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
349 Top level title
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
350 ===============
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
351
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
352 Sub title
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
355 ### Header 3
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 #### Header 4
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
358
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
359 ##### Header 5
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
360
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
361 ###### Header 6
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
364 Lists
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
367 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
368 then indent by two spaces each level
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
369
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
370 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
371 - unordered list 1
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
372 - unordered list 2
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
373 - sub unordered item
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 1. unordered list 1
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
376 2. unordered list 2
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
377 2.1. sub unordered item
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
378 ```
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 Code blocks
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
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
383 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
384 for leading spaces if you don't need syntax.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
385
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
386 ```cpp
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
387 std::cout << "hello world" << std::endl;
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
388 ```
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
389
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
390 And without syntax:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
391
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
392 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
393 This is simple code block.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
394 ```
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 Tables
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
397 ------
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
398
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
399 Tables are supported and formatted as following:
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 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
402 | header 1 | header 2 |
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 | item 1 | item 2 |
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
405 ```
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 Alerts
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
408 ------
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 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
411 different block depending on the output format:
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 - Note:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
414 - Warning:
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
415 - Danger:
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 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
418
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
419 ```markdown
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
420 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
421 it is split and indented.
c188e9603faf misc: add basic documentation files
David Demelier <markand@malikania.fr>
parents:
diff changeset
422 ```