Mercurial > molko
annotate STYLE.md @ 646:7e1eb7f6c049 default tip @
misc: remove .clang
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sun, 04 Feb 2024 15:24:37 +0100 |
parents | 19782ea1cf4a |
children |
rev | line source |
---|---|
366
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
15
diff
changeset
|
1 Molko's Engine CODING STYLE |
13
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 | 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 ``` |