From 2130e17736eff22311d65bf77638695ada584997 Mon Sep 17 00:00:00 2001
From: Water-Melon <melon-c@hotmail.com>
Date: Sun, 3 Dec 2023 19:48:56 +0800
Subject: [PATCH] chore(docs): update README and docs

---
 README.md            | 19 +++++++++--
 docs/coroutine.md    | 12 +++----
 docs/datatype.md     | 29 +++++++++++++---
 docs/flowcontrol.md  | 78 +++++++++++++++++++++-----------------------
 docs/function.md     | 30 ++++++++---------
 docs/index.md        |  2 ++
 docs/injection.md    | 18 +++++-----
 docs/installation.md | 67 +++++++++++++++++++++++++++++++++++++
 docs/operator.md     | 59 ++++++++++++++++++++++++++-------
 docs/pipe.md         | 25 ++++++++++++--
 docs/preprocess.md   | 16 ++++-----
 docs/reactive.md     | 10 +++---
 docs/reflection.md   | 10 +++---
 docs/set.md          | 22 ++++++-------
 docs/statement.md    |  6 +++-
 docs/variable.md     | 10 ++----
 16 files changed, 284 insertions(+), 129 deletions(-)
 create mode 100644 docs/installation.md

diff --git a/README.md b/README.md
index 2bd109f..b294f7d 100644
--- a/README.md
+++ b/README.md
@@ -37,13 +37,26 @@ $ make install
 
 After installed, you can execute these commands below:
 
-```
+```bash
 melang -v //show version
 melang -h //help information
 melang a.mln b.mln ... //execute melang files
 ```
 
-**Example**
+
+
+### Docker Image
+
+If you need to quickly start a Melang runtime environment, you can use this Docker image.
+
+```bash
+docker pull melonc/melon
+```
+
+
+
+### **Example**
+
 ```
 //example.m
 
@@ -59,11 +72,13 @@ Hello World!
 ```
 
 
+
 ### Applications
 
 [Meproc](https://github.com/MelonCTech/Meproc): a cross-platform process management and supervision service.
 
 
+
 ### License
 
 [BSD-3-Clause License](https://github.com/Water-Melon/Melang/blob/master/LICENSE)
diff --git a/docs/coroutine.md b/docs/coroutine.md
index 6336d3f..06a9b71 100644
--- a/docs/coroutine.md
+++ b/docs/coroutine.md
@@ -2,7 +2,7 @@
 
 Coroutine in Melang is time-sharing scheduled in a single thread.
 
-If you use the execution file which is generated by the repository on Github, script files in a same melang command will be executed in one process one thread.
+If you use the execution file which is generated by the repository on Github, script files in a same melang command will be executed in one process or even one thread.
 
 e.g.
 
@@ -13,15 +13,15 @@ $ ./melang a.mln b.mln ...
 
 
 
-Besides this way, there is a function named *eval* to start a new script task in the current thread to execute a piece of code.
+Besides this way, there is a function named `Eval` to start a new script task in the current thread to execute a piece of code.
 
 ```
 Eval(val, data, in_string, alias);
 ```
 
-If `in_string` is true, `val` is the script code, otherwise `val` is the script file path.
+If `in_string` is true, `val` will be the script code, otherwise `val` is the script file path.
 
-`data` will be passed to the new script task. If we want to use `data` in new task, we can use the variable named `EVAL_DATA` which is an internal variable added by `Eval`.
+`data` will be passed to the new script task. If we want to use `data` in new task, we can use the variable named `EVAL_DATA` which is a built-in variable added by `Eval`.
 
 `data` not support all data types, it just supports:
 
@@ -83,7 +83,7 @@ Here are two comprehensive examples of HTTP server. There are some functions whi
 
 
 
-There are two files: *server.mln* and *worker.mln*.
+There are two files: `server.mln` and `worker.mln`.
 
 Example 1.
 
@@ -116,7 +116,7 @@ net.tcp_close(fd);
 sys.print('quit');
 ```
 
-Now, you can use *ab (apache bench)* to test.
+Now, you can use `ab (apache bench)` to test.
 
 
 
diff --git a/docs/datatype.md b/docs/datatype.md
index 5cfeda8..18f0540 100644
--- a/docs/datatype.md
+++ b/docs/datatype.md
@@ -12,6 +12,7 @@ But every value has its type. Types in Melang are shown below:
 - array
 - set
 - object
+- function
 
 
 
@@ -43,10 +44,30 @@ d = ['age': 18, 'name': 'Mr. M'];
 human {
   name;
   age;
+  @run () { // this is a method definition.
+    //...
+  }
 }
 
 //value of o is an object or instance of set human.
 o = $human;
+
+//access object properties
+o.name;
+o.age = 1;
+
+//accessing non-existent object properties
+o.gender // nil will be given
+o.phone_number = 123; // the value of the new property `phone_number` has been set to 123.
+
+//here is a function definition
+@foo()
+{
+  //...
+}
+
+// and here is a function call
+foo();
 ```
 
 
@@ -61,9 +82,9 @@ a = [1, 2, 3];
 a[0]; //array[index]
 ```
 
-*a[0]* is getting the first element *1* in array *a*. And *a[2]* is the last element *3*.
+`a[0]` retrieves the first element `1` from the array `a`, while `a[2]` retrieves the last element `3`.
 
-If the index is greater than or equal to array length, *nil* will be got.
+If the index is greater than or equal to the array length, `nil` will be given.
 
 
 
@@ -73,10 +94,10 @@ There is another kind of array named *dict*.
 d = ['name': 'Tom', 'age': 18];
 ```
 
-Now if we want to access the element which *key* is *name*, we can do it in this way:
+Now if we want to access the element which *key* is `name`, we can do it in this way:
 
 ```
 d['name']; //dict[key]
 ```
 
-If *key* is not in this dict,  *nil* will be got.
+If *key* is not in this dict,  `nil` will be given.
diff --git a/docs/flowcontrol.md b/docs/flowcontrol.md
index 9b4552f..6a45136 100644
--- a/docs/flowcontrol.md
+++ b/docs/flowcontrol.md
@@ -31,24 +31,24 @@ if (conditions) {
 } fi
 ```
 
-*conditions* is one or more expressions.
+`conditions` is one or more expressions.
 
-The boolean value of *conditions* is not only including *true* and *false*, but also including any other values. So there are some values will be treated as *false*:
+The boolean value of `conditions` is not only including `true` and `false`, but also including any other values. So there are some values will be treated as `false`:
 
-- nil
-- 0
-- '' (null string)
-- [] (empty array)
+- `nil`
+- `0`
+- `''` (null string)
+- `[]` (empty array)
 
-In mode A: if conditions are satisfied (boolean value is *true*), interpreter will execute statements in *if* block.
+In mode A: if conditions are satisfied (boolean value is *true*), interpreter will execute statements in `if` block.
 
-In mode B: if conditions are satisfied, interpreter will execute statements in *if* block, otherwise *else* block statements will be executed.
+In mode B: if conditions are satisfied, interpreter will execute statements in `if` block, otherwise `else` block statements will be executed.
 
 > if there is only one statement in *if* or *else* block, the curly brackets around statement can be omitted.
 >
-> In mode B, the last *fi* can be omitted.
+> In mode B, there is no *fi* at the end of the statement block.
 
-There is a special case -- if - else if, e.g.
+There is a special case -- `if` - `else if`, e.g.
 
 ```
 if (a == 1)
@@ -58,7 +58,7 @@ else if (a == 10)
 fi
 ```
 
-Actually it just a combination of mode B and mode A. The last *if* statement is ONE statement, so we can omit curly brackets.
+Actually it just a combination of mode B and mode A. The last `if` is a single statement, so we can omit curly brackets.
 
 e.g.
 
@@ -124,11 +124,11 @@ for (expr1; expr2; expr3) {
 
 Interpreter will follow these steps to execute:
 
-1. execute *expr1* (expression).
-2. execute *expr2* and test its boolean value. if *true*, go to step3, otherwise go to step5.
-3. executed statements in *for* block.
-4. executed *expr3*, and go to step 2.
-5. *for* statement finished.
+1. execute `expr1` (expression).
+2. execute `expr2` and check its boolean value. if it is *truthy*, go to step3, otherwise go to step5.
+3. executed statements in `for` block.
+4. executed `expr3`, and go to step 2.
+5. `for` statement finished.
 
 > If there is only one statement in *for* block, the curly brackets around statement can be omitted.
 
@@ -154,13 +154,13 @@ while (conditions) {
 }
 ```
 
-*conditions* is one or more expressions.
+`conditions` is one or more expressions.
 
 Interpreter will follow these steps to execute:
 
-1. test *conditions*, if its boolean value is *true*, go to step 2, otherwise go to step 3.
-2. execute statements in *while* block and then go to step 1.
-3. *while* statement finished.
+1. test `conditions`, if its boolean value is `true`, go to step 2, otherwise go to step 3.
+2. execute statements in `while` block and then go to step 1.
+3. `while` statement finished.
 
 > If there is only one statement in *while* block, the curly brackets around statement can be omitted.
 
@@ -173,7 +173,7 @@ while (i < 10) {
 }
 ```
 
-#### 
+
 
 #### switch
 
@@ -193,10 +193,10 @@ switch (expr) {
 
 Interpreter will follow these steps:
 
-1. execute *expr* and record its value in interpreter.
-2. use *expr*'s value to match every case *value*. If matched (two values are same), go to step 3, otherwise go to step 2 to keep matching. If no case matched, and there is a *default* case in switch, the *default* will be matched, then go to step3. Otherwise go  to step 5.
+1. execute `expr` and record its value in interpreter.
+2. use `expr`'s value to match every case value. If matched (two values are same), go to step 3, otherwise go to step 2 to keep matching. If no case matched, and there is a `default` case in `switch`, the `default` will be matched, then go to step3. Otherwise go to step 5.
 3. executed statements those in matched case.
-4. keep executing next case statements but NOT to match case *value*. If there is any one case (including *default*) behind current one, go to step 4.
+4. keep executing next case statements but NOT to match case value. If there is any one case (including `default`) behind current one, go to step 4.
 5. *switch* statement finished.
 
 e.g.
@@ -215,7 +215,7 @@ switch (i) {
 }
 ```
 
-*break* statement which will be talked soon makes interpreter stop running in *switch*.
+`break` statement which will be talked soon makes interpreter stop running in `switch`.
 
 
 
@@ -227,12 +227,12 @@ Syntax:
 goto label;
 ```
 
-*goto* tells interpreter to go to a specified position marked by *label* and keep executing from the position.
+The `goto` statement tells the interpreter to jump to the specified position marked by the `label`, and continue execution from that position.
 
 e.g.
 
 ```
-sys = Import('sys');
+  sys = Import('sys');
 
   i = 10;
   goto plus;
@@ -242,9 +242,9 @@ plus:
   sys.print(i);
 ```
 
-*plus* is a label. The output of this code is 12 which means *i--;* is not executed.
+*plus* is a label. The output of this code is `12` which means `i--;` is not executed.
 
-> `goto` in Melang is a simplified.
+> `goto` in Melang is simplified.
 
 ```
 @foo()
@@ -262,7 +262,7 @@ l1:
 foo();
 ```
 
-The interpreter will throw an error that `l1` can not be found, because it is not in the outest statements in a function.
+The interpreter will throw an error that `l1` can not be found, because it is not in the outest statements in a function. The next example is working correctly.
 
 ```
 @foo()
@@ -280,13 +280,11 @@ li:
 foo();
 ```
 
-But this example is working correctlly.
-
 
 
 #### break
 
-*break* is a single statement. It is used to interrupt current loop (including *switch*), and jump out of the loop.
+`break` is a single statement. It is used to interrupt current loop (including `switch`), and jump out of the loop.
 
 e.g.
 
@@ -301,17 +299,17 @@ for (i = 0; i < 1000; i++) {
 sys.print(i);
 ```
 
-The output is 11, because when *i* greater than 10, *if* condition is matched. Then *break* statement makes *for* loop stop and go to execute next statement (*sys.print(i);*).
+The output is `11`, because when `i` greater than `10`, `if` condition is matched. Then `break` statement makes `for` loop stop and go to execute next statement (`sys.print(i);`).
 
 
 
 #### continue
 
-*continue* statement is also used in a loop (**except** *switch*).
+`continue` statement is also used in a loop (**except** `switch`).
 
-When interpreter encounter *continue* statement, the rest statements those behind *continue*, will not be executed, and go back to the beginnig of loop statements.
+When interpreter encounter `continue` statement, the rest statements those behind `continue`, will not be executed, and go back to the beginnig of loop statements.
 
-If *continue* is encountered in a  *for* loop, *expr3* and *expr2* will be executed and then back to the beginning of loop statements or finish loop (boolean value of *expr2* is *false*).
+If `continue` is encountered in a  `for` loop, `expr3` and `expr2` will be executed and then back to the beginning of loop statements or finish loop (boolean value of `expr2` is `false`).
 
 e.g.
 
@@ -333,11 +331,11 @@ Syntax:
 return value;
 ```
 
-Usually, return is used in a function. It will stop interpreter executing rest statement and return a value to the caller (outer scope).
+Usually, `return` is used in a function. It will stop interpreter executing rest statement and return a value to the caller (outer scope).
 
-*value* can be omitted, then the return value will be *nil*.
+`value` can be omitted, then the return value will be `nil`.
 
-If *return* appears in the outest scope, interpreter will stop execution, and this script task will be removed.
+If `return` appears in the outest scope, interpreter will stop execution, and this script task will be removed.
 
 e.g.
 
diff --git a/docs/function.md b/docs/function.md
index a00798c..412c0f1 100644
--- a/docs/function.md
+++ b/docs/function.md
@@ -19,11 +19,11 @@ Syntax:
 }
 ```
 
-*funcname* is the name of function, it has to follow the rule:
+`funcname` is the name of function, it has to follow the rule:
 
 > start with letter or underscore and the rest part can be number, letter or underscore.
 
-*parameters* is a series of variables, like: *name*, *age* or anything you need.
+`parameters` is a series of variables, like: `name`, `age` or anything you need.
 
 e.g.
 
@@ -34,7 +34,7 @@ e.g.
 }
 ```
 
-Here is a function named *plus*. It has two parameters named *a* and *b*. And its function is to calculate the sum of two parameters.
+Here is a function named `plus`. It has two parameters named `a` and `b`. And its function is to calculate the sum of these two parameters.
 
 
 
@@ -46,9 +46,9 @@ Syntax:
 funcname(arguments);
 ```
 
-*funcname* is the name of defined function.
+`funcname` is the name of defined function.
 
-*arguments* is a series of values.
+`arguments` is a series of values.
 
 e.g.
 
@@ -56,7 +56,7 @@ e.g.
 plus(1, 2);
 ```
 
-*plus* is the *funcname*, and 1, 2 correspond to parameter *a* and *b*.
+`plus` is the *funcname*, and `1` and `2` correspond to parameter `a` and `b`.
 
 
 
@@ -74,7 +74,7 @@ a = 0;
 a = foo(a);
 ```
 
-This program just modified *a* from 0 to 100, and that is what we wish it to be.
+This program just modified `a` from `0` to `100`, and that is what we wish it to be.
 
 But the last statement is a little bit clumsy. How to make it better?
 
@@ -88,9 +88,9 @@ a = 0;
 foo(a);
 ```
 
-We change function parameter *data* to be *&data*.
+We change function parameter `data` to be `&data`.
 
-Operator *&* makes argument *a* to be a reference variable named *data* in function *foo*. Every modification on *data* will directly effect on *a*.
+Operator `&` makes argument `a` to be a reference variable named `data` in function `foo`. Every modification on `data` will directly effect on `a`.
 
 > Note:
 >   1. & only can be used on the parameters of function definition.
@@ -109,7 +109,7 @@ Operator *&* makes argument *a* to be a reference variable named *data* in funct
 foo();
 ```
 
-This program will not report error. Because interperter will set *nil* to *data* automatically.
+This program will not report error. Because interperter will set `nil` to `data` automatically.
 
 
 
@@ -129,9 +129,7 @@ Let's see an example:
 @foo()();
 ```
 
-Guess what happened?
-
-'bar' will be printed on terminal.
+`bar` will be printed on terminal.
 
 It is possible because function definition is a statement. So we can define a function in another function's definition.
 
@@ -162,11 +160,9 @@ The result of this program is:
 argument list: this is a variable arguments example 
 ```
 
-The key point is variable *args*. It's a internal variable in Melang function.
-
-It is an array to record every arguments passed to this function.
+The key point is variable `args`. This is a built-in variable that exists only in functions where the number of actual parameters exceeds the number of formal parameters.
 
-> Function *sys.size* returns the number of array elements.
+This is an array used to record all actual parameter values that do not have corresponding formal parameters.
 
 
 
diff --git a/docs/index.md b/docs/index.md
index 07c4504..922273f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -18,6 +18,8 @@ Now, let's start our journey.
 
 ### Contents
 
+[Installation](https://water-melon.github.io/Melang/installation.html)
+
 [Data types](https://water-melon.github.io/Melang/datatype.html)
 
 [Operators](https://water-melon.github.io/Melang/operator.html)
diff --git a/docs/injection.md b/docs/injection.md
index 1b24c53..8b7a04e 100644
--- a/docs/injection.md
+++ b/docs/injection.md
@@ -8,9 +8,9 @@ Human {
 someone = $Human;
 ```
 
-Now, we have a set *Human* without any property or method, and an object of *Human* named *someone*.
+Now, we have a set `Human` without any property or method, and an object of `Human` named `someone`.
 
-So as a human, *someone* must has age. Let's add for it.
+So as a human, `someone` must has age. Let's add for it.
 
 ```
 sys = Import('sys');
@@ -18,9 +18,9 @@ someone.age = 20;
 sys.print(someone.age);
 ```
 
-OK, done. Now *20* will be printed on terminal.
+OK, done. Now `20` will be printed on terminal.
 
-Let's add a method for *someone*.
+Let's add a method for `someone`.
 
 ```
 @printAge()
@@ -33,7 +33,7 @@ someone.print = printAge;
 someone.print();
 ```
 
-*printAge* is a function not object method, but it can be treated as an object method by injection. In a common function, *this* is *nil*. So if call *printAge* directly, interpreter will throw an error.
+`printAge` is a function not object method, but it can be treated as an object method by injection. In a regular function, `this` is `nil`. So if call `printAge` directly, interpreter will throw an error.
 
 
 
@@ -46,9 +46,9 @@ sys = Import('sys');
 sys.setter(object, name, value);
 ```
 
-use *sys.setter* to inject property or method into an object. Its return value is the same as argument *value*.
+use `sys.setter` to inject property or method into an object. Its return value is the same as argument `value`.
 
-Let's add a *name* in *someone*.
+Let's add a `name` in `someone`.
 
 ```
 sys = Import('sys');
@@ -65,7 +65,7 @@ Jason
 Jason
 ```
 
-Let's add a method in *someone* to print name.
+Let's add a method in `someone` to print name.
 
 ```
 Sys = Import('sys');
@@ -104,4 +104,4 @@ The output is:
 Jason
 ```
 
-But if you try to access a nonexistent property by this function, interperter will throw an error.
+But if you try to access a non-existent property by this function, interperter will throw an error.
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..1eb1bed
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,67 @@
+## Installation
+
+
+
+Melang relies on the core C library [Melon](https://github.com/Water-Melon/Melon), so it needs to be installed first. We can use the following commands to quickly install Melon:
+
+```bash
+git clone https://github.com/Water-Melon/Melon.git
+cd Melon
+./configure
+make
+sudo make install
+```
+
+If you are a Windows user, please refer to [Melon installation](http://doc.melonc.io/en/install.html) for more details.
+
+
+
+Then, we can execute the following commands to install Melang:
+
+```bash
+git clone https://github.com/Water-Melon/Melang.git
+cd Melang
+./configure
+make all
+sudo make install
+```
+
+The `configure` command has the following parameters:
+
+- `--help` Output the help information.
+- `--prefix` The installation path for Melang.
+- `--melon-prefix` The installation path for the core library Melon.
+- `--lib-prefix` The installation path for the dynamic libraries used by the Melang.
+- `--enable-mysql` Enable the MySQL feature, which means compiling the MySQL dynamic library used by Melang.
+- `--mysql_header_path` The header files path for libmysqlclient (If they cannot be found in `/usr/include` or any other default header loading path).
+- `--mysql_lib_path` The library path for libmysqlclient (If they cannot be found in `/usr/lib` or any other default library loading path.).
+- `--enable-wasm` Compile into a wasm format file.
+- `--debug` Enable debug mode, which is used for developing and debugging Melang.
+
+
+
+Now you can use Melang for development.
+
+### Example
+
+Here is a Melang script file.
+
+```
+//example.m
+
+sys = Import('sys');
+sys.print("Hello World!");
+```
+
+Then execute
+
+```bash
+melang example.m
+```
+
+The output is
+
+```
+Hello World!
+```
+
diff --git a/docs/operator.md b/docs/operator.md
index 40e70e3..0a76439 100644
--- a/docs/operator.md
+++ b/docs/operator.md
@@ -22,33 +22,68 @@ These operators are listed by priority from low to high.
 
 
 
-e.g.
+### Examples
 
-Try to execute these statements, and guess their results.
+Here, it is assumed that you have already installed Melang and all its library files (installed using the `make all` command).
+
+The `sys.print` will output the contents of the parameter to the terminal.
 
 ```
-sys = import('sys');
+sys = Import('sys');
 
-i = 1, 2, 3; //guess i = ?, you can use function sys.print to output on your terminal
-sys.print(i);
+i = 1, 2, 3;
+sys.print(i); // 1
 
-i += 1; //increase 1
+i += 1;
+sys.print(i); // 2
 
 b = i == 2; //b is a boolean value
+sys.print(b); // true
+
+i = i | 1;
+sys.print(i); // 3
+
+sys.print(i++); // 3
 
-i = i | 1; //guess i = ?
+sys.print(++i); // 5
 
-i++;
+sys.print(i--); // 5
 
---i;
+sys.print(--i); // 3
 
-//Instantiate a human object
-human {
+sys.print(i == 3 && 100 || 50); // 100
+
+human { // set definition
   name;
   age;
 }
-friend = $human; //friend is an object
+friend = $human; //instantiate a human object
 friend.name = 'Alex';
 friend.age = 18;
+sys.print(friend.name); // Alex
+sys.print(friend.age); // 18
+
+sys.print(!friend.age); //false
+
+arr = [1, 2, 3];
+sys.print(arr[2]); // 3
+```
+
+The output is:
+
+```
+1
+2
+true
+3
+3
+5
+5
+3
+100
+Alex
+18
+false
+3
 ```
 
diff --git a/docs/pipe.md b/docs/pipe.md
index 02ae210..7f2f2c4 100644
--- a/docs/pipe.md
+++ b/docs/pipe.md
@@ -2,7 +2,7 @@
 
 
 
-Pipe provides an approach to send a data set from C layer to script layer.
+The pipe provides a way for the C level to communicate with the script level.
 
 
 
@@ -27,7 +27,27 @@ This function will send a data set given by `...` to a specified script task by
 Return value:
 
 - `0` on success
-- `-1` fails
+- `-1` on failure
+
+
+
+```c
+int mln_trace_recv_handler_set(mln_lang_ctx_pipe_recv_cb_t recv_handler);
+
+typedef int (*mln_lang_ctx_pipe_recv_cb_t)(mln_lang_ctx_t *, mln_lang_val_t *);
+```
+
+This function is used to receive data from the script level in C code.
+
+The parameters of `recv_handler`:
+
+- the first one is the script task context object.
+- the second one is the data sent from script level.
+
+Return value:
+
+- `0` on succes
+- `-1` on failure
 
 
 
@@ -44,6 +64,7 @@ This function is used to subscribe, unsubscribe and receive data from C layer.
 - `subscribe` starts to accept data set.
 - `unsubscribe` stop to accept data set.
 - `recv` receive data set.
+- `send` send data to C level.
 
 Return value:
 
diff --git a/docs/preprocess.md b/docs/preprocess.md
index 5ff66b9..f21b720 100644
--- a/docs/preprocess.md
+++ b/docs/preprocess.md
@@ -12,7 +12,7 @@ Like preprocess in C, Melang supports simple preprocess.
 #undef NAME //undefine macro
 ```
 
-*Name* is equivalent to 'John'. Melang just simply replace 'NAME' with 'John' in code.
+`Name` is equivalent to `'John'`. Melang just simply replace `NAME` with `'John'` in code.
 
 
 
@@ -32,15 +32,15 @@ Like preprocess in C, Melang supports simple preprocess.
 #endif
 ```
 
-In example A, if *NAME* is defined, code A will be executed.
+In example A, if `NAME` is defined, code A will be executed.
 
-In example B, if NAME is defined, code B will be executed, otherwise execute code C.
+In example B, if `NAME` is defined, code B will be executed, otherwise execute code C.
 
 
 
 #### include
 
-Just like *include* in C, Melang also support it to load some script files into a file.
+Just like `include` in C, Melang also support it to load some script files into the current file.
 
 **Note: the included file must be quoted by double quotes.**
 
@@ -57,11 +57,11 @@ The path should follow these rules:
 
 - if path is an absolute path, just try to load it.
 
-- if path is not a absolute path, interpreter will search for file in the following order:
+- if path is not an absolute path, interpreter will search for file in the following order:
 
   1. if there is the file in current directory, just load it.
-  2. if there is a environment variable named *MELANG_PATH* which points to some directories, interpreter will search for file in them. If interpreter cannot find file, an error would be occurred.
-  3. if step 1 and step 2 are failed, interpreter will search for file in */usr/lib/melang/*.
+  2. if there is a environment variable named `MELANG_PATH` which points to some directories, interpreter will search for file in them.
+  3. if step 1 and step 2 are failed, interpreter will search for file in `/usr/lib/melang/` (This path can be changed during the installation of Melon by passing parameters to the `configure`.).
 
   If failed, an error would be occurred.
 
@@ -73,6 +73,6 @@ Another example:
 #include "@/b.m"
 ```
 
-`@` is a special char stands for base directory of current file (`a.m`). So its value is `/xxx/yyy'.
+`@` is a special char stands for base directory of current file (`a.m`). So its value is `/xxx/yyy`.
 
 So `/xxx/yyy/b.m` will be included in `a.m`.
diff --git a/docs/reactive.md b/docs/reactive.md
index 83eee2d..f9137ab 100644
--- a/docs/reactive.md
+++ b/docs/reactive.md
@@ -18,7 +18,7 @@ Reactive programming is based on two functions:
 
 But these functions are bound with interpreter tightly, so they won't be achieved in library.
 
-Calling *watch* to trace a variable, a callback function will be called after the variable's value changed.
+Calling `watch` to trace a variable, a callback function will be called after the variable's value changed.
 
 e.g.
 
@@ -46,9 +46,9 @@ hello
 hello
 ```
 
-As we can see in this example, if `watch` is called, *handler* will be called when *a*'s value changed.
+As we can see in this example, if `watch` is called, `handler` will be called when `a`'s value changed.
 
-We should note that *handler* is a function, its parameter supports reference. So in this example, *newValue* and *userData* are not references. So every modification on *userData* can not affect on the outer scope variable as we wish.
+We should note that `handler` is a function, its parameter supports reference. In this example, `newValue` and `userData` are not references. So every modification on `userData` can not affect on the outer scope variable as we wish.
 
 So let's fix this problem.
 
@@ -78,11 +78,11 @@ world
 
 
 
-If we don't want to trace this variable any more, we can use *Unwatch* to stop tracing.
+If we don't want to trace this variable any more, we can use `Unwatch` to stop tracing.
 
 ```
 Unwatch(a);
 a = 13;
 ```
 
-*handler* won't be called any more, and nothing will be printed on terminal.
+`handler` won't be called any more, and nothing will be printed on terminal.
diff --git a/docs/reflection.md b/docs/reflection.md
index 0e09660..2c0dc9a 100644
--- a/docs/reflection.md
+++ b/docs/reflection.md
@@ -16,7 +16,7 @@ a = 'foo';
 a();
 ```
 
-As we can see, variable *a* is a string not function, but its value is a function name. So the last statement will output 'foo' on terminal.
+As we can see, variable `a` is a string but a function, but its value is a function name. The last statement will output `foo` on terminal, because function `foo` is called.
 
 Let's see a more complex example:
 
@@ -31,7 +31,7 @@ b = 'a';
 b();
 ```
 
-This example will output 'foo' on terminal either.
+This example will output `foo` on terminal either.
 
 
 
@@ -49,9 +49,9 @@ Tom = $s;
 sys.print(Tom);
 ```
 
-*s* is a string variable, and its value is a set name.
+`s` is a string variable, and its value is a set name.
 
-The output is *Object*. Which means, *Tom = $s;* is working. *Tom* is an object of set *human*.
+The output is `Object`. Which means, `Tom = $s;` is working. `Tom` is an object of set `human`.
 
 
 
@@ -83,7 +83,7 @@ The result of this program is:
 running
 ```
 
-The first part is a set reflection to instantiate an *human* object. And set object's *action* to be a string which is the method name *run*. And then call object method via object property.
+The first part is a set reflection to instantiate an `human` object. And set object's `action` to be a string which is the method name `run`. And then call object method via object property.
 
 > Note: The code shown below is not working.
 >
diff --git a/docs/set.md b/docs/set.md
index ace450c..c9c6d69 100644
--- a/docs/set.md
+++ b/docs/set.md
@@ -33,14 +33,14 @@ human {
 }
 ```
 
-*human* is a set name. It has some properties: *name, age, gender, score*. And one method: *init*.
+`human` is a set name. It has some properties: `name`, `age`, `gender`, `score`. And one method: `init`.
 
 In this example, you can see:
 
 - property definition just need a name
-- method definition has a special local variable named *this*
+- method definition has a special local variable named `this`
 
-*this* is an internal variable in method. It is a reference to set's object.
+`this` is an built-in variable in method. It is a reference to set's object.
 
 
 
@@ -51,9 +51,9 @@ Now we have two questions:
 
 Set is an abstract definition and object is a instantiated Set.
 
-As shown above, set *human* is a definition. It defines some basic attributes of a human.
+As shown above, `human` is a set definition. It defines some basic attributes of a human.
 
-So if there is a boy named Tom, and he also has these attributes, then he is an instance of set *human*, which means Tom is an object of set *human*.
+So if there is a boy named Tom, and he also has these attributes, then he is an instance of `human`, which means Tom is an object of set `human`.
 
 So how to instantiate a set object?
 
@@ -61,9 +61,9 @@ So how to instantiate a set object?
 Tom = $human;
 ```
 
-That's done. Now, we have a variable named *Tom*, and that is an object of set *human*.
+That's done. Now, we have a variable named `Tom`, and that is an object of set `human`.
 
-Now, we can visit *Tom*'s properties and methods.
+Now, we can visit `Tom`'s properties and methods.
 
 ```
 sys = Import('sys');
@@ -73,10 +73,10 @@ Tom.init('Tom Moore', 8, 'male');
 sys.print(Tom.name);
 ```
 
-The first line is calling method *init*, this method initiates object *Tom*'s properties.
+The first line is calling method `init`, this method initiates object `Tom`'s properties.
 
-The last line outputs *Tom*'s name.
+The last line outputs `Tom`'s name.
 
-And we can see, if we want to visit an object's property or method, we need to use operator *.* (dot). Left of operator . is an object and right is object's property or method.
+And we can see, if we want to access an object's property or method, we need to use operator `.` (dot). Left of operator `.` is an object and right is object's property or method.
 
-Back to the topic *this*. In this example, *this* is a reference of object *Tom*. So modifications on *this* will directly affect on *Tom*. So the result of the last one statement is 'Tom Moore'.
+Back to the topic `this`. In this example, `this` is a reference of object `Tom`. So modifications on `this` will directly affect on `Tom`. So the output of the last one statement is `Tom Moore`.
diff --git a/docs/statement.md b/docs/statement.md
index 631c4ef..8ce0baa 100644
--- a/docs/statement.md
+++ b/docs/statement.md
@@ -20,12 +20,16 @@ In this example, first line is a statement, and second one is a statement too. A
 ```
 a = 1, c = 3;
 b = 2;
+
+// function definition
 @c() {
   return 1;
 }
+
+//set definition
 @d {
   p = 1;
-  @q () {
+  @q () { //another function definition
     return 2;
   }
 }
diff --git a/docs/variable.md b/docs/variable.md
index 2fe3992..5c9de25 100644
--- a/docs/variable.md
+++ b/docs/variable.md
@@ -43,12 +43,12 @@ The result is:
 nil
 ```
 
- That is reasonable because interpreter just search *a* in current scope (in function *foo*), and it is not defined in this scope.
+ That is reasonable because interpreter just search `a` in current scope (in function *foo*), and it is not defined in this scope.
 
-But if we need a's value in foo, how to do?
+If we need to obtain the value of a global variable, then the global variable's name should begin with a capital letter.
 
 ```
-A = 1;
+A = 1; // global variable A
 @foo() {
   sys = Import('sys');
   sys.print(A);
@@ -62,10 +62,6 @@ Result is:
 1
 ```
 
-So here is the special rule:
-
-> If variable name start with an upper case character, it will be searched from current scope and outest scope.
-
 
 
 Let's see another example: