# MLstate/opalang

### Subversion checkout URL

You can clone with HTTPS or Subversion.

 88296dd [doc] CONTRIBUTING: added a CONTRIBUTING.md file to support github contr... Aqua-Ye authored Oct 2, 2012 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 f5b2865 [doc] CONTRIBUTING: merged stdlib guidelines Aqua-Ye authored Oct 3, 2012 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 88296dd [doc] CONTRIBUTING: added a CONTRIBUTING.md file to support github contr... Aqua-Ye authored Oct 2, 2012 283 # Opa Documentation format : 85e602c [doc] DOCUMENTATION: added a DOCUMENTATION file for future usage Aqua-Ye authored Feb 11, 2012 284 4cb2cce [enhance] CONTRIBUTING.md: enabled the section about Opa documentation f... Aqua-Ye authored Oct 30, 2012 285  85e602c [doc] DOCUMENTATION: added a DOCUMENTATION file for future usage Aqua-Ye authored Feb 11, 2012 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 * }] c208b2a [doc] CONTRIBUTING: typo on doc format example Aqua-Ye authored Nov 15, 2012 369 * {R right} [{R 370 * right 85e602c [doc] DOCUMENTATION: added a DOCUMENTATION file for future usage Aqua-Ye authored Feb 11, 2012 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 */ 4cb2cce [enhance] CONTRIBUTING.md: enabled the section about Opa documentation f... Aqua-Ye authored Oct 30, 2012 411