Merge pull request #114 from caseykneale/master

Some Docs suggestions

docs/benchmark.md

@@ -1,10 +1,10 @@
 # Benchmark
 
-In terms of data shape validation, MLStyle can be strictly faster than even a carefully optimized handwritten code.
+In terms of data shape validation, MLStyle can often be faster than carefully optimized handwritten code.
 
-All benchmark scripts are provided in the directory [Matrix-Benchmark](https://github.com/thautwarm/MLStyle.jl/blob/master/matrix-benchmark).
+All of the scripts for the benchmarks are provided in the directory: [Matrix-Benchmark](https://github.com/thautwarm/MLStyle.jl/blob/master/matrix-benchmark).
 
-To run these cross-implementation benchmarks, some extra dependencies should be installed:
+To run these cross-implementation benchmarks, some extra Julia packages should be installed:
 
 - `(v1.4) pkg> add Gadfly MacroTools Rematch Match BenchmarkTools StatsBase Statistics ArgParse DataFrames`.
 
@@ -16,11 +16,11 @@ The benchmarks presented here are made by Julia **v1.4** on **Windows 10(64 bit)
 
 *Benchmark results for other platforms and Julia versions are welcome to get accepted as a pull request, if you figure out a better way to organize the files and their presentations in this README.*
 
-(*We rule out the benchmarks of the space use, it's considered unnecessary as the cost are always zero which is not only for MLStyle*)
+(*We leave out the benchmarks of the space used. That should be considered unnecessary as the costs are always zero. *)
 
 On the x-axis, after the name of test-case is the least time-consuming run's index in units of `ns`.
 
-The y-label is the ratio of the implementation's time cost to that of the least time-consuming.
+The y-axis is the ratio of the implementation's time cost, made relative to that of the least time-consuming.
 
 The benchmark results in dataframe format are available at [this directory](https://github.com/thautwarm/MLStyle.jl/tree/master/stats).
 
@@ -58,4 +58,4 @@ The benchmark results in dataframe format are available at [this directory](http
 
 - code: [matrix-benchmark/bench-vs-match.jl](https://github.com/thautwarm/MLStyle.jl/blob/master/matrix-benchmark/bench-vs-match.jl)
 
-[![matrix-benchmark/bench-versus-match.jl](https://raw.githubusercontent.com/thautwarm/MLStyle.jl/master/stats/bench-versus-match.svg)](https://github.com/thautwarm/MLStyle.jl/blob/master/stats/bench-vs-match.txt)
+[![matrix-benchmark/bench-versus-match.jl](https://raw.githubusercontent.com/thautwarm/MLStyle.jl/master/stats/bench-versus-match.svg)](https://github.com/thautwarm/MLStyle.jl/blob/master/stats/bench-vs-match.txt)

docs/how.md

@@ -2,4 +2,4 @@
 
 For installation, open the package manager mode in the Julia REPL and `add MLStyle`.
 
-For more examples or tutorials, see [this project](https://github.com/thautwarm/MLStyle-Playground) which will be frequently updated to present some interesting uses of MLStyle.jl.
+For more examples or tutorials, see [the MLStyle-Playground project](https://github.com/thautwarm/MLStyle-Playground). This project will be frequently updated to demonstrate some interesting uses of MLStyle.jl.

docs/modules/ast.md

@@ -4,7 +4,7 @@ MLStyle.Modules.AST
 @matchast
 ---------------------
 
-- Description: Similar to `@match`, but focus on AST matching. No need to quote patterns with `quote ... end` or `:(...)`.
+- Description: Similar to `@match`, but the focus is on AST matching. There is no need to quote patterns with `quote ... end` or `:(...)`.
 - Usage: `@matchast ast_to_match (begin cases... end)`
 - Examples:
 
@@ -44,7 +44,7 @@ Dict{Symbol,Dict}(:s1 => Dict{Any,Any}(),:s2 => Dict{Symbol,Dict{Any,Any}}(:s1 =
 @capture
 -------------------
 
-- Description: Similar to `MacroTools.@capture`, but provided with a more regex-flavored matching.
+- Description: Similar to `MacroTools.@capture`, but provides a more regex-flavored matching.
 
 - Usage: `@capture template input_ast`,  note that `template` is purely static and cannot be a variable from current context.
 
@@ -73,4 +73,4 @@ outputs
 │      :a     => :a
 │      :b     => :b
 └      :stmts => Any[:(#= REPL[8]:1 =#), :(a + b)]
-```
+```

docs/syntax/adt.md

@@ -105,7 +105,7 @@ using MLStyle
 end
 ```
 
-Above codes makes a clarified description about Arithmetic operations and provides a corresponding implementation.
+The above code makes a clear description about Arithmetic operations and provides a corresponding implementation.
 
 If you want to transpile above ADTs to some specific language, there is a clear step:
 
@@ -137,7 +137,7 @@ About Type Parameters
 
 `where` is used for type parameter introduction.
 
-Following 2 patterns are equivalent:
+The following 2 patterns are equivalent:
 ```julia
 A{T1...}(T2...) where {T3...}
 A{T1...}(T2...) :: A{T1...} where {T3...}

docs/syntax/pattern.md

@@ -1,7 +1,7 @@
-Patterns
+Pattern Matching
 =======================
 
-Patterns provide convenient ways to manipulate data. The basic syntax for pattern matching with MLStyle is of the form
+Pattern matching provides convenient ways to manipulate data. The basic syntax for pattern matching with MLStyle is of the form
 ```julia
 @match data begin
     pattern1 => result1
@@ -10,7 +10,7 @@ Patterns provide convenient ways to manipulate data. The basic syntax for patter
     patternn => resultn
 end
 ```
-MLStyle will first test if `data` is matched by `pattern1` and if it does match, return `result1`. If `pattern1` does not match, then MLStyle moves on to the next pattern. If no pattern in the list matches `data`, an error is thrown.
+MLStyle will first test if `data` is matched by `pattern1` and if it does match, return `result1`. If `pattern1` does not match, then MLStyle moves on to the next pattern in sequence. If no pattern in the list matches `data`, an error is thrown.
 
 In version 0.4.1 and newer, if you only have a single pattern you may instead write
 ```julia
@@ -32,7 +32,7 @@ julia> @match 10 begin
        end
 "right!"
 ```
-All literal data introduced with Julia syntax could be matched by literal patterns.
+All literal data introduced with Julia syntax can be matched by literal patterns.
 
 However, note that the equality is strict for primitive types(`Int8-64`, `UInt8-64`, `Bool`, etc.) and singleton types(`struct Data end; Data()`).
 
@@ -82,10 +82,10 @@ julia> @match 1.0 begin
 ```
 
 Unlike most of ML languages or other libraries who only permit guards in the end of a case clause,
-MLStyle allows you to put guards anywhere during matching.
+MLStyle.jl allows you to put guards anywhere during matching.
 
 However, remember, due to some Julia optimization details, even if the guards can be put
-in the middle of a matching process, still you'd better postpone it to the end of matching, for better performance.
+in the middle of a matching process, it is still better to postpone it until the end of matching sequence. This allows for better performance.
 
 Sometimes, in practice, you might want to introduce type variables into the scope, in this case use `where` clause, and see [Advanced Type Patterns](#advanced-type-patterns) for more details.
 
@@ -113,7 +113,7 @@ julia> @match (1, 2) begin
 true
 ```
 
-Destructuring Tuple Array and Dict Patterns
+Destructuring Tuples, Arrays, and Dictionaries with Pattern Matching
 ---------------------
 
 - Tuple Patterns
@@ -163,7 +163,7 @@ julia> @match dict begin
 7
 ```
 
-Note that, due to the lack of an operation for distinguishing `nothing` from "key not found" in Julia's standard library, the dictionary pattern has a little overhead. Things will get solved after [Julia#34821](https://github.com/JuliaLang/julia/pull/34821) gets done.
+Note that, due to the lack of an operation for distinguishing `nothing` from "key not found" in Julia's standard library, the dictionary pattern has a little overhead. This will be resolved after [Julia#34821](https://github.com/JuliaLang/julia/pull/34821) is completed.
 
 **P.S**:  MLStyle will not refer an external package to solve this issue, as MLStyle is generating "runtime support free" code, which means that any code generated by MLStyle itself depends only on Stdlib. This feature allows MLStyle to be introduced as a dependency only in development, instead of being distributed together to downstream codes.
 
@@ -695,7 +695,7 @@ end # true
 
 The pattern `quote .. end` is equivalent to `:(begin ... end)`.
 
-Additionally, you can use any other patterns simultaneously when matching asts. In fact, there're regular patterns inside a `$` expression of your ast pattern.
+Additionally, you can use any other patterns simultaneously when matching ASTs. In fact, there are regular patterns inside a `$` expression of your AST pattern.
 
 A more complex example presented here might help with your comprehension about this:
 
@@ -747,7 +747,7 @@ end
 #   :app_arg        => :d
 ```
 
-Here is several articles about Ast Patterns.
+If you are interested, here are several useful articles about AST Patterns:
 
 - [A Modern Way to Manipulate ASTs](https://www.reddit.com/r/Julia/comments/ap4xwr/mlstylejl_a_modern_way_to_manipulate_asts/).
 

docs/syntax/switch.md

@@ -1,10 +1,9 @@
 The Switch Statements
 ===============================
 
-In the real use of pattern matching provided by MLStyle,
-things can sometimes becomes painful. To end this, we have `@when`, and now even **`@switch`**.
+Not all real-world code is most conveniently expressed using `@match`. To help with some common pain-points, we have included `@when`, and **`@switch`**.
 
-Following code is quite stupid in many aspects:
+The following example demonstrates a common pattern that is unnecessarily verbose:
 
 ```julia
 var = 1
@@ -17,7 +16,7 @@ var = 1
 
 Firstly, capturing in `@match` just shadows outer variables, but sometimes you just want to change them.
 
-Secondly, `@match` is an expression, and the right side of `=>` can be only an expression, and writing a `begin end` there can bring bad code format.
+Secondly, `@match` is an expression, and the right side of `=>` can only be an expression. Therefore writing `begin` or `end` statements can bring about an undesirable code format.
 
 To address these issues, we present the `@switch` macro:
 
@@ -42,4 +41,4 @@ julia> @switch 1 begin
            println(var)
        end
 ERROR: matching non-exhaustive, at #= REPL[25]:1 =#
-```
+```

docs/syntax/when.md

@@ -1,12 +1,12 @@
 When Destructuring
 ===========================
 
-The `@when` is introduced to work with the scenarios where `@match` is a bit heavy.
+The `@when` macro was introduced to work with the scenarios where `@match` leads to heavy syntax.
 
 It's similar to [if-let](https://doc.rust-lang.org/rust-by-example/flow_control/if_let.html) construct in Rust language.
 
 
-There're three distinct syntaxes for `@when`.
+There are three distinct syntaxes for `@when`.
 
 Allow Destructuring in Let-Binding
 -----------------------------------------------------------------
@@ -45,7 +45,7 @@ s = S1(5)
     end
 ```
 
-In above snippet, `@inline fn(x) = 100x` is not regarded as destructuring.
+In the above snippet, `@inline fn(x) = 100x` is not regarded as destructuring.
 
 
 Sole Destructuring
@@ -74,10 +74,9 @@ Sometimes we might have this kind of logic:
 - otherwise do `Cc`
 
 
-As there is now no pattern matching support for `if-else`,
-we cannot represent above logic literally in vallina Julia.
+As there is currently no pattern matching support for `if-else`, we cannot represent above logic literally in vallina Julia.
 
-MLStyle provides this, in such a syntax:
+MLStyle provides this, with the following syntax:
 
 ```julia
 @when let A = a
@@ -89,7 +88,7 @@ MLStyle provides this, in such a syntax:
 end
 ```
 
-Also, predicates can be used here, thus it's superior than
+Also, predicates can be used here, thus it can be seen as superior to
 `if-else`:
 
 ```julia
@@ -105,7 +104,7 @@ Also, predicates can be used here, thus it's superior than
 end
 ```
 
-A concrete example is presented here:
+A concrete example is presented below:
 
 ```julia
 a = 1
@@ -115,4 +114,4 @@ b = 2
 @when begin a::Int = b; (b < 10).? end
     0
 end # => 0
-```
+```

docs/tutorials/capture.md

@@ -4,20 +4,20 @@ Static Capturing
 We know that `MacroTools.jl` has brought about a useful macro
 `@capture` to capture specific structures from a given AST.
 
-As the motivation of some contributors, `@capture` of `MacroTools.jl` has 3 following shortages.
+As the motivation of some contributors, `@capture` of `MacroTools.jl` has the following 3 short comings.
 
-- Use underscore to denote the structures to be captured, like `struct typename_ field__ end`, which makes you have to manually number the captured variables and not that readable or consistent.
+- An underscore is used to denote the structures which are to be captured, like `struct typename_ field__ end`, which makes you have to manually number the captured variables. This is not very readable or consistent.
 
-- Cause Side-Effect. The captured variables are entered in current scope.
+- Causes Side-Effects. The captured variables are entered in current scope.
 
-- Lack functionalities like conditional capturing.
+- Lacks functionalities like conditional capturing.
 
-We can implement several new `@capture` via MLStyle.jl to get better in all aspects.
+We can implement several new `@capture` via MLStyle.jl to get better results in all of these aspects.
 
 `Capture` Pattern from `MLStyle.Modules.AST`:
 ----------------------------------------------------------
 
-MLStyle now can collaborate with scope information very well. You can get the captured(by pattern matching) variables in one point of your program.
+MLStyle now can collaborate with scope information very well. You can get the captured variables by pattern matching in one point of your program.
 
 ```julia
 using MLStyle.Modules.AST
@@ -67,4 +67,4 @@ node2 = :(f(x))
 end
 
 # do nothing
-```
+```