WIP

Author: hhugo

doc/dev/manual/bindings.wiki

@@ -79,12 +79,55 @@ end
 === Method name mangling
 
 OCaml method names are transformed to JavaScript names using underscore
-conventions. This enables binding to capitalized names (use {{{_Foo}}} for
-{{{Foo}}}) and overloaded methods (use {{{foo_int}}} and {{{foo_string}}} for
-the same {{{foo}}} method).
+conventions. When accessing a field of an object, the name given in OCaml
+is transformed by:
+1. Removing a leading underscore (if present)
+2. Removing all characters starting from the last underscore
+
+This enables:
+- **Capitalized names**: Use {{{_Foo}}} to refer to JavaScript's {{{Foo}}}
+- **Reserved words**: Use {{{_type}}} to refer to JavaScript's {{{type}}}
+- **Method overloading**: Use {{{foo_int}}} and {{{foo_string}}} for the same {{{foo}}} method
+
+==== Examples
+
+<<code language="ocaml"|
+class type canvas = object
+  (* All three refer to the same JS method: drawImage *)
+  method drawImage :
+      imageElement Js.t -> int -> int -> unit Js.meth
+  method drawImage_withSize :
+      imageElement Js.t -> int -> int -> int -> int -> unit Js.meth
+  method drawImage_fromCanvas :
+      canvasElement Js.t -> int -> int -> unit Js.meth
+end
+>>
+
+==== Full naming rules
+
+<<code language="ocaml"|
+class type example = object
+  (* All of these refer to JS field [meth] *)
+  method meth : ..
+  method meth_int : ..
+  method _meth_ : ..
+  method _meth_aa : ..
 
-See <<a_manual chapter="library"|the library documentation>> for the full
-naming rules and examples.
+  (* All of these refer to JS field [meth_a] *)
+  method meth_a_int : ..
+  method _meth_a_ : ..
+  method _meth_a_b : ..
+
+  (* Refer to [Meth] (capitalized) *)
+  method _Meth : ..
+
+  (* Refer to [_meth] (leading underscore in JS) *)
+  method __meth : ..
+
+  (* Refer to [_] *)
+  method __ : ..
+end
+>>
 
 === Binding constants from a class
 

doc/dev/manual/build-toplevel.wiki

@@ -1,46 +1,40 @@
-= How to build a toplevel =
+= Building a toplevel
 
 First, initialize the toplevel using {{{Js_of_ocaml_toplevel.JsooTop.initialize}}}.
 
-Then, build your bytecode program with debug enabled (**-g**) and linkall (**-linkall**). You should obviously link in all the libraries you want accessible in the final toplevel.
+Then, build your bytecode program with debug enabled ({{{-g}}}) and linkall ({{{-linkall}}}). Link in all the libraries you want accessible in the final toplevel.
 
-Finally, compile your toplevel to JavaScript passing the {{{--toplevel}}} flags to the js_of_ocaml compiler.
+Finally, compile your toplevel to JavaScript passing the {{{--toplevel}}} flag to the js_of_ocaml compiler.
 
 If you want to limit the set of modules available in the toplevel, you can explicitly pass a list of compilation units that should be accessible using the {{{--export FILE}}} flag.
-**FILE** must contain names of compilation unit to export - one per line. The **jsoo_listunits** tool, provided by the **js_of_ocaml-toplevel** opam package, can be used to generate this list
-from a set of findlib libraries.
+{{{FILE}}} must contain names of compilation units to export, one per line. The {{{jsoo_listunits}}} tool, provided by the {{{js_of_ocaml-toplevel}}} opam package, can be used to generate this list from a set of findlib libraries.
 
-For example, the following command will create a file **FILE** containing all compilation unit names provided by the findlib libraries **stdlib** and **str**.
+For example, the following command will create a file containing all compilation unit names provided by the findlib libraries {{{stdlib}}} and {{{str}}}:
 {{{
-  jsoo_listunits -o FILE stdlib str
+jsoo_listunits -o units.txt stdlib str
 }}}
 
+= Using the Dynlink library
 
-Note that toplevels currently cannot be built using separate compilation.
+OCaml supports dynlink of bytecode files using the {{{dynlink}}} library. To use it when compiled to JavaScript:
 
+1. Link {{{js_of_ocaml-compiler.dynlink}}} to initialize dynlink support (initialization is automatic via side-effect)
+2. Build your bytecode program with debug enabled ({{{-g}}}) and linkall ({{{-linkall}}})
+3. Compile your program to JavaScript passing the {{{--dynlink}}} flag
 
-= How to build a program using the **Dynlink** library =
+== Example
 
-OCaml supports dynlink of bytecode files using the **dynlink** library. In order to work when compiled to JavaScript, one needs to follow the following steps:
-
-First, make sure to link **js_of_ocaml-compiler.dynlink** to initialize the support for dynlink (the initialization is done automatically by side-effect).
-
-Then, build your bytecode program with debug enabled (**-g**) and linkall (**-linkall**).
-
-Finally, compile your program to JavaScript passing the {{{--dynlink}}} flags to the js_of_ocaml compiler.
-
-Here is an example showing how to compile and use a program using Dynlink:
 {{{
-  # cat main.ml
-  let () = Dynlink.loadfile "./plugin.cmo"
+# main.ml
+let () = Dynlink.loadfile "./plugin.cmo"
 
-  # Compiling main program
-  ocamlfind ocamlc -linkpkg -package dynlink -package js_of_ocaml-compiler.dynlink main.ml -o main.bc
-  js_of_ocaml main.bc --dynlink
+# Compiling main program
+ocamlfind ocamlc -linkpkg -package dynlink -package js_of_ocaml-compiler.dynlink main.ml -o main.bc
+js_of_ocaml main.bc --dynlink
 
-  # Compiling plugin
-  ocamlfind ocamlc -c plugin.ml
+# Compiling plugin
+ocamlfind ocamlc -c plugin.ml
 
-  # Test
-  node ./main.js
+# Test
+node ./main.js
 }}}

doc/dev/manual/debug.wiki

@@ -17,10 +17,11 @@ See <<a_manual chapter="errors"|Error handling>> for details on attaching
 JavaScript stack traces to OCaml exceptions using {{{OCAMLRUNPARAM=b=1}}} or
 the {{{--enable with-js-error}}} compiler flag.
 
-== Breakpoint
-One can set breakpoints using developers tools (see https://developer.chrome.com/devtools/docs/javascript-debugging).
-Alternatively, one can set breakpoints programmatically by calling {{{Js.debugger ()}}}. Note that
-browsers will only stop at breakpoints when developers tools are in use.
+== Breakpoints
+
+Set breakpoints using browser developer tools (see https://developer.chrome.com/docs/devtools/javascript).
+Alternatively, set breakpoints programmatically by calling {{{Js.debugger ()}}}. Note that
+browsers only stop at breakpoints when developer tools are open.
 
 == Source map
 Source map is used to map the generated JavaScript code to original sources.
@@ -30,4 +31,4 @@ step through the code, and inspect variables directly in OCaml sources.
 == About Chrome DevTools
 Useful settings for Chrome DevTools:
 * Display variable values inline while debugging
-* Resolve variable names (hidden DevTools Experiments, see http://islegend.com/development/how-to-enable-devtools-experiments-within-google-chrome)
+* Resolve variable names (hidden DevTools Experiments, see https://developer.chrome.com/docs/devtools/settings/experiments)

doc/dev/manual/effects.wiki

@@ -1,27 +1,40 @@
-== Effect handlers ==
+= Effect handlers
 
-Js_of_ocaml supports effect handlers with the {{{--enable=effects}}}
-flag. This is based on partially transforming the program to
-continuation-passing style.
-As a consequence, [[tailcall|tail calls]] could be fully optimized (if CPS transformed).
-This is not the default for now since the generated code can be slower,
-larger and less readable.
-The transformation is based on an analysis to detect parts of the code that cannot involve effects and keep it in direct style.
-The analysis is especially effective on monomorphic code. It is not so effective when higher-order functions are heavily used ({{{Lwt}}}, {{{Async}}}, {{{incremental}}}).
-We hope to improve on this by trying alternative compilation
-strategies.
+Js_of_ocaml supports effect handlers with the {{{--effects=cps}}} flag.
+This is based on partially transforming the program to continuation-passing style.
+As a consequence, <<a_manual chapter="tailcall"|tail calls>> can be fully optimized
+(when CPS transformed).
 
-An alternative CPS transform is provided under the {{{--effects=double-translation}}} option. It keeps a direct-style version of the transformed functions in addition to the CPS version. The choice of running the CPS version is delayed to run time. Since CPS code is usually slower, this can avoid degradations. In addition, one can ensure that some code is run in direct style by using {{{Jsoo_runtime.Effect.assume_no_perform}}}.
+This is not the default because the generated code can be slower, larger, and
+less readable. The transformation uses an analysis to detect parts of the code
+that cannot involve effects and keeps them in direct style. The analysis is
+especially effective on monomorphic code but less effective when higher-order
+functions are heavily used ({{{Lwt}}}, {{{Async}}}, {{{Incremental}}}).
 
-=== Dune integration ===
+== Double translation mode
 
-Dune is aware of the {{{--enable effects}}} option. So, you can just add it to the Js_of_ocaml flags {{{(js_of_ocaml (flags ...))}}} wherever you want to use it.
+An alternative CPS transform is provided with {{{--effects=double-translation}}}.
+It keeps a direct-style version of the transformed functions in addition to the
+CPS version. The choice of running the CPS version is delayed to run time.
 
-We're still working on dune support for the {{{--effects}}} option. For now, here are two possible setups.
+Since CPS code is usually slower, this can avoid performance degradations. You can
+also ensure that some code runs in direct style using
+{{{Jsoo_runtime.Effect.assume_no_perform}}}.
 
-=== Whole dune workspace setup ===
+== Dune integration
+
+Dune is aware of the {{{--effects}}} option. You can add it to the
+js_of_ocaml flags wherever you want to use it:
+
+{{{
+(js_of_ocaml (flags ...))
+}}}
+
+=== Whole workspace setup
+
+To enable effects for the entire workspace, add this to a {{{dune}}} or
+{{{dune-workspace}}} file at the root:
 
-Put the following in a {{{dune}}} (or {{{dune-workspace}}}) file at the root of the workspace
 {{{
 (env
  (_
@@ -30,25 +43,31 @@ Put the following in a {{{dune}}} (or {{{dune-workspace}}}) file at the root of
    (build_runtime_flags (:standard --effects=double-translation)))))
 }}}
 
-With this setup, one can use both separate and whole program compilation.
+This setup supports both separate and whole program compilation.
 
+=== Per-executable setup
 
-=== Sub directory setup ===
+To enable effect handlers for specific binaries only, you need to use whole
+program compilation:
 
-If you want to enable effect handlers for some binaries only, you'll
-have to give up separate compilation for now using:
 {{{
 (executable
-  (name main)
-  (js_of_ocaml
-   (compilation_mode whole_program)
-   (flags (:standard --effects=double-translation)))
-)
+ (name main)
+ (js_of_ocaml
+  (compilation_mode whole_program)
+  (flags (:standard --effects=double-translation))))
 }}}
 
-Trying to use separate compilation would result in an error while attempting to link the final js file.
+Using separate compilation with effects enabled only for some executables will
+result in a linking error:
+
 {{{
 js_of_ocaml: Error: Incompatible build info detected while linking.
  - test6.bc.runtime.js: effects=disabled
  - .cmphash.eobjs/byte/dune__exe.cmo.js: effects=double-translation
 }}}
+
+== See also
+
+* <<a_manual chapter="options"|Command line options>> - Full list of {{{--effects}}} modes
+* <<a_manual chapter="tailcall"|Tailcall optimization>> - How tail calls interact with effects