Merge pull request #504 from jimt/spelling

Fix docs spelling/punctuation.

docs/Compiler-options.md

@@ -7,13 +7,13 @@ so that you can do
 ```bash
 bsc -bs-files *.ml *.mli
 ```
-The compiler will sort the order of input files before starting compilation
+The compiler will sort the order of input files before starting compilation.
 
 * -bs-module
 
-Specify the JavaScript module system to use in the generated JavaScript code. Supported values are `commonjs`, `amdjs` and `goog:<namespace>`
+Specify the JavaScript module system to use in the generated JavaScript code. Supported values are: `commonjs`, `amdjs` and `goog:<namespace>`
 
-When you want to use `goog` module system, you can do things like this:
+When you want to use the `goog` module system, you can do things like this:
 
 ```bash
 bsc -bs-module goog xx.ml 
@@ -23,7 +23,7 @@ bsc -bs-module goog:bloomberg.buckle.test xx.ml
   # namespace is bloomberg.buckle.test
 ```
 
-You would then need a bundler for different the different module systems: `webpack` supports `commonjs` and `amdjs` while `google closure compiler` supports all.
+You would then need a bundler for the different module systems: `webpack` supports `commonjs` and `amdjs` while `google closure compiler` supports all.
 
 *  -bs-gen-tds
 

docs/Compiler-overview.md

@@ -1,6 +1,6 @@
 ## High Level compiler workflow
 
-The high level architecture is illustrated as below:
+The high level architecture is illustrated below:
 
 ```
 Source Language
@@ -48,18 +48,18 @@ The current design of BuckleScript follows several high level principles. While
 
 **Lambda Representation** 
 
-As pictured in the diagram above BuckleScript is primarily based on the Lambda representation of the OCaml compiler. While this representation is quite rich, some information is lost from upstream representation. The patch to the OCaml compiler tries to enrich this representation in a non-intrusive way (see next section). 
+As pictured in the diagram above, BuckleScript is primarily based on the Lambda representation of the OCaml compiler. While this representation is quite rich, some information is lost from the upstream representation. The patch to the OCaml compiler tries to enrich this representation in a non-intrusive way (see next section). 
 
 **Minimal Patch to the OCaml compiler**
 
-BuckleScript requires patches to the OCaml compiler. One of the main reason is to enrich the Lambda representation so that the generated code is as nice as possible. A design goal is to keep those patches minimal and useful for the OCaml compiler in general so that they can later be integrated. 
+BuckleScript requires patches to the OCaml compiler. One of the main reasons is to enrich the Lambda representation so that the generated code is as nice as possible. A design goal is to keep those patches minimal and useful for the OCaml compiler in general so that they can later be integrated. 
 
->A common question is to wonder why BuckleScript transpiles OCaml record value to JavaScript array while a more intuitive representation would be a JavaScript object. This technical decision is a direct consequence of the above 2 design principles: the Lambda layer assumes in a lot of places that a record value is an array and such modification would be too large of a change to OCaml compiler.
+>A common question is to wonder why BuckleScript transpiles an OCaml record value to a JavaScript array while a more intuitive representation would be a JavaScript object. This technical decision is a direct consequence of the above 2 design principles: the Lambda layer assumes in a lot of places that a record value is an array and such modification would be too large of a change to OCaml compiler.
 
 **Soundness**
 
 BuckleScript preserves the soundness of the OCaml language. Assuming the FFI is correctly implemented, the type safety is preserved. 
 
 **Minimal new symbol creation** 
 
-In order to make the JavaScript generated code as close as possible to the original OCaml core we thrive to introduce as little new symbols as possible. 
+In order to make the JavaScript generated code as close as possible to the original OCaml core we thrive to introduce as few new symbols as possible. 

docs/Create-a-simple-example-with-NPM.md

@@ -8,9 +8,9 @@ cd npm_test
 echo "{}" > package.json
 ```
 
-First, Install BuckleScript.
-(For more advacned settings, please read
-[Installation](./Installation.md))
+First, install BuckleScript.
+(For more advanced settings, please read
+[Installation](./Installation.md).)
 
 
 

docs/Dev-mode-How-to.md

@@ -1,6 +1,6 @@
 ### Build the compiler
 
-The development of BuckleScript compiler relies on 2 tools which are readily available in `opam` and work with our patch OCaml compiler:
+The development of BuckleScript compiler relies on 2 tools which are readily available in `opam` and work with our patched OCaml compiler:
 - [ocamlbuild](http://caml.inria.fr/pub/docs/manual-ocaml-400/manual032.html): Default build tool for OCaml project 
 - [camlp4](https://github.com/ocaml/camlp4): Tool used to generate OCaml code for processing large AST. (j.ml file). 
 
@@ -20,4 +20,4 @@ cd ./runtime; make all
 
 ```sh
 cd ./stdlib; make all
-```
+```

docs/Extensions.md

@@ -88,8 +88,8 @@ f_uncurry(3,"x")
 However, for curried function application, it depends on how compiler
 optimizations goes, for most cases, when the compiler see the
 definition of `f`, it will compile it in the most efficient way, i.e,
-JS full aplication, if the compiler can not see the definition of `f`,
-it will do a runtime dispath, so there are two possible outputs:
+JS full application, if the compiler can not see the definition of `f`,
+it will do a runtime dispatch, so there are two possible outputs:
 
 ```js
 Curry._2(f, 3, "x") // compiler fails to optimize
@@ -147,7 +147,7 @@ fun [@bs] x y -> x + y (* arity of 2*)
 
 - class type
 
-BuckleScript overrides OCaml `class type` syntax for FFI, to trigger this, 
+BuckleScript overrides OCaml `class type` syntax for FFI. To trigger this, 
 you have to put a file level configuration in the beginning.
 
 ```ocaml
@@ -196,7 +196,7 @@ type y3 = _y3 Js.t
 ```
 
 Which is equivalent to type definitions as below:
-(Note that user can not write such type definitions, but its semantics-equivalent )
+(Note that user can not write such type definitions, but it's semantically equivalent.)
 
 ```ocaml
 class type _y =
@@ -272,10 +272,10 @@ function uu(x,y){
 
 # Embedding raw JS code
 
-Note this is not encouraged, user is always encouraged to minimize and localize use cases 
-of embedding raw Javascript code, however, sometimes it's useful to get the job done quickly
+Note this is not encouraged. The user is always encouraged to minimize and localize use cases 
+of embedding raw Javascript code, however, sometimes it's useful to get the job done quickly.
 
-- Ebedding raw JS code as an expression
+- Embedding raw JS code as an expression
 
 ```ocaml
 let keys : t -> string array [@bs] = [%bs.raw "Object.keys" ]

docs/FAQ.md

@@ -1,4 +1,4 @@
 
 * The compiler does not build
 
-  In production mode, the compiler is a single file in `jscomp/bin/compiler.ml`, if it is not compiling, make sure you have the right OCaml compiler version. Currently OCaml Compiler is a submodule of bucklescript. Make sure the exact commit hash matches (we only update the compiler occasionally).
+  In production mode, the compiler is a single file in `jscomp/bin/compiler.ml`. If it is not compiling, make sure you have the right OCaml compiler version. Currently the OCaml compiler is a submodule of bucklescript. Make sure the exact commit hash matches (we only update the compiler occasionally).

docs/Help-move-runtime-functions-from-OCaml-to-Javascript.md

@@ -8,11 +8,11 @@ Currently all tests are in `jscomp/test` directory and you should either add a n
 
 * Add the filename in `jscomp/test/test.mllib`
 
-* Add a  suite test
+* Add a suite test
 
    The specification is in `jscomp/test/mt.ml`
 
-   For example a simple tests would be like
+   For example some simple tests would be like:
 
    ```ocaml
    let suites : _ Mt.pair_suites = Mt.[
@@ -24,7 +24,7 @@ Currently all tests are in `jscomp/test` directory and you should either add a n
    let () = Mt.from_pair_suites __FILE__ suites
    ```
 
-* Run the test
+* Run the tests
 
    Suppose you have mocha installed, if not, try `npm install mocha`
 
@@ -36,4 +36,4 @@ Currently all tests are in `jscomp/test` directory and you should either add a n
 
    ```
    npm run cover
-   ```
+   ```

docs/How-to-adapt-your-build-system.md

@@ -1,10 +1,10 @@
-BuckleScript compilation model is the same as the OCaml compiler. 
+The BuckleScript compilation model is the same as the OCaml compiler. 
 
 If `b.ml` depends on `a.ml`, you have to compile `a.ml` **and** `a.mli` first. 
 
-> The technical reason is that BuckleScript will generate intermediate file with extension `.cmj` which are later used for cross module inlining and other information. 
+> The technical reason is that BuckleScript will generate intermediate files with the extension `.cmj` which are later used for cross module inlining and other information. 
 
-Find below a simple Makefile to get started:
+Here is a simple Makefile to get started:
 
 ```make
 OCAMLC=bsc
@@ -31,4 +31,4 @@ all: $(TARGETS)
 
 depend:                                                                                                                                                                                           
         $(OCAMLDEP) $(INCLUDES) $(SOURCE_ML) $(SOURCE_MLI) | sed -e 's/\.cmx/.cmj/g' > .depend    
-```
+```

docs/Installation.md

@@ -1,6 +1,6 @@
 ## Introduction
 
-To use BuckleScript, you need both, a specific version of the OCaml compiler (tweaked to make BuckleScript possible), and the BuckleScript software itself. The instructions below show how to install both of these using standard package managers as well as how to build from source for Unix/Linux systems. Build directions will be updated once Windows systems are supported.
+To use BuckleScript, you need both a specific version of the OCaml compiler (tweaked to make BuckleScript possible), and the BuckleScript software itself. The instructions below show how to install each of these using standard package managers as well as how to build from source for Unix/Linux systems. Build directions will be updated once Windows systems are supported.
 
 ## Default installation procedure (using package managers)
 
@@ -16,7 +16,7 @@ opam switch 4.02.3+buckle-1
 eval `opam config env`
 ```
 
-> This step is optional. npm installation will build the compiler from source if not installed from opam
+> This step is optional. npm installation will build the compiler from source if not installed from opam.
 
 ### 2. BuckleScript from npm (required)
 
@@ -28,7 +28,7 @@ npm install --save bs-platform
 
 ## Advanced installation procedure (from source)
 
-BuckleScript has very little dependencies and building from source can easily be done.
+BuckleScript has very few dependencies and building from source can easily be done.
 
 ### 1. OCaml compiler
 
@@ -63,7 +63,7 @@ which you can add to your `$PATH`. You could also set an environment variable
 pointing to the stdlib, e.g. `BSC_LIB=/path/to/jscomp/stdlib` for ease of use.
 
 Note that by default, `bsc` will generate `commonjs` modules, you can
-override such behavior by picking up your own module system:
+override such behavior by picking your own module system:
 
 ```sh
 MODULE_FLAGS='-bs-module amdjs' make world

docs/JS-call-OCaml.md

@@ -1,4 +1,4 @@
-# JS Call OCaml
+# JS Calling OCaml
 
 Since BuckleScript guarantees that all OCaml functions are exported as is, no extra work is required to expose OCaml function to JavaScript.
 
@@ -8,7 +8,7 @@ Some things need be taken care of:
    want to export those external functions, please write `val` instead. 
 
 * `operators` are escaped, since Javascript does not support user
-   defined operators, for example instead of calling `Pervasives.(^)`,
+   defined operators. For example instead of calling `Pervasives.(^)`,
    you have to call `Pervasives.$caret` from your Javascript functions
-   (TODO: document the conversion rules)
+   (TODO: document the conversion rules).
 

docs/JavaScript-target-versions.md

@@ -1,21 +1,21 @@
-BuckleScript targets to **ES5**
+BuckleScript targets **ES5**.
 
 Below is a list of polyfills from ES6 needed:
 
 **Math.imul** 
 
-This polyfill is needed for `int32`multiplication. The polyfill is actually implemented in the generated code. 
+This polyfill is needed for `int32` multiplication. The polyfill is actually implemented in the generated code. 
 
 >No action is required by the user.
 
 **TypedArray**
 
-For the following functions requires the TypedArray polyfill:
+The following functions require the TypedArray polyfill:
 * Int64.float_of_bits
 * Int64.bits_of_float 
 * Int32.float_of_bits
 * Int32.bits_of_float 
 
->The TypedArray polyfill is not provided by BuckleScript and it's the responsibility of the user to bundle the polyfill implementation of its choice with the BuckleScript generated code.
+>The TypedArray polyfill is not provided by BuckleScript and it's the responsibility of the user to bundle the desired polyfill implementation with the BuckleScript generated code.
 
 >For the current BuckleScript version, if the user does not bundle the TypedArray polyfill and the JavaScript engine does not support it, the code will fail at runtime. 

docs/NPM-Support.md

@@ -1,11 +1,11 @@
 
-BuckleScript extends OCaml compiler options with several flags to
+BuckleScript extends the OCaml compiler options with several flags to
 provide better experience for NPM users.
 
 ## To deploy your OCaml library as a npm package
 
 In general, you are expected to deploy two kinds of artifacts, the
-generated JS files and meta data which your OCaml dependents relies
+generated JS files and meta data which your OCaml dependencies rely
 on.
 
 Since CommonJS has no namespaces, to allow JS files live in different
@@ -16,9 +16,9 @@ bsc -bs-npm-output-path $npm_package_name:path/to/your/js/dir -c a.ml
 ```
 
 By passing this flag, `bsc` will store your `package_name` and
-relative path to `package.json` in `.cmj` files, it will also generate
-JS files in the directory you specified, you can and are encouraged
-to store js files in a hierarchical directory.
+relative path to `package.json` in `.cmj` files. It will also generate
+JS files in the directory you specified. You can, and are encouraged
+to, store js files in a hierarchical directory.
 
 For the binary artifacts, (Note that this is not necessary if you only
 want your libraries to be consumed by JS developers, and it has
@@ -33,8 +33,8 @@ and js files in a *hierachical* directory
 
 ## To use OCaml library as a npm package
 
-If you follow the layout convention above, use ocaml package is pretty
-straightforward
+If you follow the layout convention above, using an OCaml package is pretty
+straightforward:
 
 ```
 bsc -bs-npm-package-include ocaml-library -c a.ml
@@ -44,7 +44,7 @@ bsc -bs-npm-package-include ocaml-library -c a.ml
 
 ## Conclusion
 
-Your command line would be like this
+Your command line would be like this:
 
 ```
 bsc -bs-npm-package-include ocaml-library1 -bs-npm-package-include