Skip to content
This repository
Newer
Older
100644 411 lines (326 sloc) 12.668 kb
88296ddd » Aqua-Ye
2012-10-02 [doc] CONTRIBUTING: added a CONTRIBUTING.md file to support github co…
1 # Naming conventions:
2
3 * the language is called Opa, not OPA or opa;
4 * respectively, other languages are called JavaScript, OCaml, HTML, PHP;
5 * the BSL is the Binding System Library;
6
7 # Spelling conventions:
8 * we are writing in American, so use the "z" of your keyboard;
9 * full words, please, not "we're" but "we are", no "it's" but "it is", etc.
10
11 # Chapter conventions:
12 * tutorials start with "Hello"
13
14 # Convention for source code:
15 * source code must fit in 80 columns;
16 * source must be fully commented, in Opadoc style;
17 * keywords are between ++
18
19 # Typography:
20 * don't forget semi-colons;
21 * in lists, they are compulsory.
22
23 # Git commits:
24 * commit messages must respect the following format:
25 * [tag] context: message
26 * where allowed tags are:
27 * cleanup, contrib, debug, doc, enhance, feature, fix, layout, revert.
28
29 # ChangeLog conventions:
30
31 YEAR.MONTH.DAY, Version SEMVER (stability), GIT_HASH
32
33 * change 1
34 - description
35
36 * change 2
37
38 * change 3
39
f5b28657 » Aqua-Ye
2012-10-03 [doc] CONTRIBUTING: merged stdlib guidelines
40 # Stdlib
41
42 ## How to write an Opa module
43
44 Read this before writing an Opa module.
45 If you don't, chances are that the module will not be kept.
46
47 The role of these guidelines is to make sure that:
48
49 - we can find our way in the code easily
50 - we produce documentation for end-users
51 - your changes break neither the compiler nor the user's code.
52
53 ### I. All code must be documented.
54
55 For examples of documented code, see the existing code.
56 Try to stay as much as possible is the same spirit, and
57 check that the generated html (opadoc) is well formed.
58
59 Documenting takes only a few minutes.
60 Understanding undocumented code takes hours or days.
61 If you don't document your code, someone will hate you passionately.
62 You have been warned.
63
64 Important Note: Don't confuse "commenting" and "documenting".
65 Comments are good but can't replace documentation.
66 Again, see the examples.
67
68 Documentation MUST indicate, among other things
69 - what the module is for
70 - who it is for ("@audience PUBLIC"/"@audience PRIVATE"/...)
71 - possibly, how it is used, by who, in particular for modules of stdlib.core,
72 because any change in this kind of modules can have an impact on the compiler.
73
74 For an example of documentation, see DOCUMENTING, in this directory,
75 or see all the existing documentation.
76
77 ### II. How should I call my module? Where should I put it?
78
79 We have a notion of packages. The compiler is fully separated with respect to
80 packages.
81
82 The main criterium for the separation of files is the packages dependencies.
83
84 Package names can be named with a '.' (dot), but it is a fake hierarchy. In
85 fact, a dot can be seen like an underscore, and packages are identifying by
86 their names, so, if it is not needed, do not go too deep in the hierarchy.
87
88 #### II.1) stdlib.core
89
90 If your module is used by the compiler, it must go to : stdlib.core
91 This package is needed for core Opa features, it contains mostly run time
92 support, like comparison, serialization, servers codes.
93
94 This package also defines its own interface for the compiler, i.e. the complete
95 set of function the compiler can insert calls on. This interface is declared by declaration tagged by @opacapi directives.
96 Theses declarations should only be toplevel aliases, on functions in stdlib.core,
97 and the name of each alias must be the full path of the function with dots
98 replaced by underscores.
99 E.g. : Value_serialize = Value.serialize
100
101 Be extremly aware of the fact that we are trying to reduce as much as possible
102 the size of the minimal server. This has also an important impact on the debugging.
103 If your module is not used by the compiler, then, it has really nothing to do in stdlib.core.
104 If you add a lot of code in stdlib.core, someone will hate you passionately.
105 You have been warned.
106
107 ##### II.2) stdlib.*
108
109 These packages are additionnaly libs we want to be part of the standard library.
110 It is still not really clear if a package should be in the stdlib, or not.
111 Probably most of generic packages developped @mlstate will be in stdlib.*
112
113 If your package is too specific, then it is probably better to make a separate package.
114
115 some example:
116 facebook -> not is stdlib, TODO: specify the package organisation.
117 fgraph -> stdlib.fgraph
118
119 If you want to add several modules related to the same thing, it would be preferable
120 to create a new package. (cf e.g. fgraph)
121 If your module is an extension of an existing package, simply add it in the corresponding package.
122
123 ### III. Code goes into modules.
124
125 Remember, by default, in Opa, everything sits in the current package namespace.
126 Every typename and every value name you create therefore pollutes the current package namespace,
127 potentially breaking someone else's code.
128
129 Consequently, all your values must be in modules, and/or restricting the interfaces
130 with the scopes directives :
131 `@public`
132 `@package`
133 `@private`
134
135 Similarly, all your types should respect the namespace conventions.
136 For the moment, we don't have a syntax to put types into record.
137 Until then, if you wish to add a type "foo" to your module "Foo", call it "Foo.foo".
138 The name of types should strictly follow the hierarchy of modules.
139
140 If you wish to add a function or a type to the global namespace, ask the Opa team first.
141 Be aware that big changes in the stdlib are dangerous because of the number of potential
142 users which already use it.
143 Be aware that if you add a function with a ugly name (or even worth, a function with a
144 name incoherent with the implementation), someone could use it the next day,
145 and if you want to change some names, and types after that, it will imply a big refactoring
146 everywhere your functions are used.
147
148 If you add function which does not follow naming conventions, or argument order conventions,
149 or any other conventions written in this file, someone will hate you passionately.
150 You have been warned.
151
152 Remember that once a Opa distribution will be done, we will no more be able to change any interfaces !
153 There is no hurry. Take your time. Review your code, ask advice for names of functions to other people,
154 it is always good to have several point of vues.
155 See also if a correspond lib does not already exists in an other language.
156 For exemple, if there is a reference API in an other language, you can keep the same names
157 (convention used e.g. in fgraph, the API is mostly preserved from OcamlGraph)
158
159 Let's say we are playing in a contest of beauty of API.
160
161 ### IV. Naming conventions.
162
163 values_look_like_this
164 ModuleLookLikeThis
165 TypesInModule.Look.like_this
166 fields_look_like_this
167 files_look_like_this.opa
168
169 Accessor functions:
170
171 get_foo
172 is_foo
173
174 Conversion functions:
175
176 Foo.of_bar
177 Foo.to_bar
178
179 ### IV. Types are closed.
180
181 When you define a new type or data structure, chances are that users don't need
182 to know how it's implemented, so you should make it @abstract (if users should
183 see the type but not its definition) or @private (if the type is purely
184 internal). This will make error messages simpler for the user and it might make
185 type-checking a tad faster.
186
187 ### V. Mutability.
188
189 Mutability is bad. You have no idea how bad it is until you've attempted to
190 execute mutable code in parallel. Consequently, mutable code should be
191 avoided. Really.
192
193 In the current versions of Opa, the unit of mutability is the session. If you
194 need mutability, use a session. If you need a global state shared by the server,
195 use [UserContext]. If you need something to be saved for future uses, use the
196 database. Don't write volatile stuff into the database. No sessions, no session
197 identifiers, etc.
198
199 If you have a use case that fits none of these, and if you are really convinced
200 that you need a reference, come and see David. He might scream at you, of
201 course.
202
203 ### V. Interacting with the compiler.
204
205 If you define a value which needs to be used by the compiler, there are a few
206 steps you need to take in order to make sure that it won't be removed
207 prematurely by a compiler optimization and/or by the persons maintaining the
208 library.
209
210 For this purpose, you should
211
212 - mark your value as @opacapi
213 - add it to opacapi/opacapi.ml
214 - in some cases, add it to the roots
215 - document how and why it's used in the compiler
216
217 ### VI. Checking that it works.
218
219 Compile with the normal procedure (make), and run tests.
220
221 ### VII. Bypasses.
222
223 Make what you want with bypasses. Do not export private bypasses.
224
225 ### VIII. Fold, map, etc.
226
227 The base loops upon each data structure are
228
229 - fold, foldi
230 - map, mapi
231 - iter, iteri
232 - filter, filteri
233 - reduce, reducei
234 - filter_map, filter_mapi
235
236 Wherever possible, data structures should also support constructors
237
238 - unfold, unfoldi
239 - init
240 - of_list
241
242 And conversion to external data structures
243
244 - to_list
245 - to_map
246
247 Unless your data structure doesn't support these constructions, they should all exist, exactly with this name.
248 If your data structure supports several folds (or several maps, etc), one of them, the default one, must be
249 called exactly "fold" (respectively "map"). Name the variants with a suffix, which makes the difference explicit
250 (e.g. "fold" -> "fold_backwards", "iteri" -> "iteri_backwards", etc.)
251
252 The order of arguments is the following, keep it consistent for all data structures:
253
254 function ( iterator, structure, [more-arguments]) : 'result
255
256 - exists: ( f:('a -> bool), structure: t('a) ): bool
257
258 - filter: ( f:'a -> bool, structure: t('a) ): t('a)
259 - filteri: ( f:int -> 'a -> bool, structure: t('a) ): t('a)
260 - filter_map: ( f:'a -> option('b), structure: t('a) ): t('b)
261 - filter_mapi: ( f:int -> 'a -> option('b), structure: t('a) ): t('b)
262
263 - fold: ( f:('item, 'acc) -> 'acc, structure: t('item), init:'acc ): 'acc
264 - foldi: ( f:(int, 'item, 'acc) -> 'acc, structure: t('item), init:'acc ): 'acc
265
266 - init: ( f:int -> 'item, size: int): t('item)
267
268 - iter: ( f:('a -> void), structure: t('a) ): void
269 - iteri: ( f:(int, 'a) -> void, structure: t('a) ): void
270
271 - map: ( f:'a -> 'b, structure: t('a) ): t('b)
272 - mapi: ( f:(int,'a) -> 'b, structure: t('a) ): t('b)
273
274 - mem: ( elt:'a, structure: t('a) ): bool
275
276 - reduce: ( f:'a -> 'a, structure: t('a) ): option('a) //{none} if the structure was empty
277 - reducei: ( f:int -> 'a -> 'a, structure: t('a) ): option('a) //{none} if the structure was empty
278
279 - unfold: ( f:'counter -> option(('item, 'counter)), init: 'counter ): t('item)
280 - unfoldi: ( f:(int, 'counter)-> option(('item, 'counter)), init: 'counter): t('item)
281
282
88296ddd » Aqua-Ye
2012-10-02 [doc] CONTRIBUTING: added a CONTRIBUTING.md file to support github co…
283 # Opa Documentation format :
85e602c3 » Aqua-Ye
2012-02-11 [doc] DOCUMENTATION: added a DOCUMENTATION file for future usage
284
4cb2cceb » Aqua-Ye
2012-10-30 [enhance] CONTRIBUTING.md: enabled the section about Opa documentatio…
285 ```
85e602c3 » Aqua-Ye
2012-02-11 [doc] DOCUMENTATION: added a DOCUMENTATION file for future usage
286 /**
287 * {1 Tests}
288 *
289 * [[**] ]
290 * [ [ **] ]
291 * [ [** ]]
292 * [[* *] ]
293 * [ [**] ]
294 * [ [**] [**] ]
295 * [ [ [**] ] ]
296 *
297 * [[]]
298 * [[][]]
299 * [[[]]]
300 * [{}]
301 * [{}{}]
302 * [{{}}]
303 *
304 * [[t[]]]
305 *
306 * {{}}
307 * {{}{}}
308 * {{{}}}
309 * {[]}
310 * {[][]}
311 * {[[]]}
312 *
313 * {[{t{}}}
314 * {[{% \emph{Hello \latex}}}
315 *
316 * {1 Syntax of documentation comments}
317 *
318 * Comments in an Opa file are parsed by opadoc to produce associated
319 * documentation. A special syntax can be used within these comments in order
320 * to organize the produced documentation and make it look better.
321 *
322 * You can either write independent documentation comments or associate them to
323 * code elements (functions, modules...) by placing them just before the
324 * element they describe.
325 *
326 * {2 Structure}
327 *
328 * You can use the following tags to organize the documentation into different
329 * parts.
330 *
331 * Square and curly brackets can be used inside formatting brackets without
332 * being escaped as long as they go in pair (opening and closing ones). If
333 * you'd like to use a single opening or closing bracket, you should escape it
334 * with a backslash.
335 *
336 * {3 Headings}
337 *
338 * {[
339 * {1 Heading1}
340 * {2 Heading2}
341 * {3 Heading3}
342 * {4 Heading4}
343 * {5 Heading5}
344 * {6 Heading6}
345 * }
346 *
347 * {3 Text formats}
348 *
349 * {4 Basic styles}
350 *
351 * {b bold}: [{b bold}]
352 *
353 * {it italic}: [{it italic}]
354 *
355 * {emp emphasize}: [{emp emphasize}]
356 *
357 * {^ superscript}: [{^ superscript}]
358 *
359 * {_ subscript}: [{_ subscript}]
360 *
361 * {4 Alignments }
362 *
363 * {C center} [{C
364 * center
365 * }]
366 * {L left} [{L
367 * left
368 * }]
c208b2a0 » Aqua-Ye
2012-11-15 [doc] CONTRIBUTING: typo on doc format example
369 * {R right} [{R
370 * right
85e602c3 » Aqua-Ye
2012-02-11 [doc] DOCUMENTATION: added a DOCUMENTATION file for future usage
371 * }]
372 *
373 * {4 Code}
374 *
375 * {[
376 * {[
377 * ...
378 * your code here
379 * ...
380 * }
381 * }
382 *
383 * {4 Verbatim}
384 *
385 * {[
386 * {v
387 * ...
388 * verbatim text here
389 * ...
390 * }
391 * }
392 *
393 * {4 Lists}
394 *
395 * {ul ul}
396 *
397 * {enum enum}
398 *
399 * {4 Raw LaTeX}
400 *
401 * {[
402 * {% \emph{Hello \latex}}
403 * }
404 *
405 * {4 Custom}
406 *
407 * {[
408 * {custom custom tag}
409 * }
410 */
4cb2cceb » Aqua-Ye
2012-10-30 [enhance] CONTRIBUTING.md: enabled the section about Opa documentatio…
411 ```
Something went wrong with that request. Please try again.