doc review

docs/source/design.rst

@@ -45,7 +45,7 @@ System Layers
 
 4. Routing(Distributed) Layer
    
-   Route MQTT messages between clustered nodes.
+   Route MQTT messages among clustered nodes.
 
 ----------------
 Connection Layer
@@ -63,11 +63,11 @@ This layer is built on the `eSockd`_ library which is a general Non-blocking TCP
 
 This layer is also responsible for encoding/decoding MQTT frames:
 
-1. Parse MQTT frame received from client
-2. Serialize MQTT frame sent to client
+1. Parse MQTT frames received from client
+2. Serialize MQTT frames sent to client
 3. MQTT Connection Keepalive
 
-Main modules of this layer:
+Main erlang modules of this layer:
 
 +------------------+--------------------------+
 | Module           | Description              |
@@ -87,7 +87,7 @@ Main modules of this layer:
 Session Layer
 -------------
 
-The session layer processes MQTT packets received from client, and deliver PUBLISH packets to client.
+The session layer processes MQTT packets received from client and delivers PUBLISH packets to client.
 
 A MQTT session will store the subscriptions and inflight messages in memory:
 
@@ -100,7 +100,7 @@ A MQTT session will store the subscriptions and inflight messages in memory:
    messages which have been received from the Client, but have not been
    completely acknowledged.
 
-4. All qos1, qos2 messages published to when client has been disconnected.
+4. All qos1, qos2 messages published to when client is disconnected.
 
 MQueue and Inflight Window
 --------------------------
@@ -113,18 +113,18 @@ Concept of Message Queue and Inflight Window::
           -----------------------------------------------
                                   |<---   Win Size  --->|
 
-1. Inflight Window to store the messages delivered and awaiting for PUBACK.
+1. Inflight Window to store the messages delivered and await for PUBACK.
 
 2. Enqueue messages when the inflight window is full.
 
-3. If the queue is full, dropped qos0 messages if store_qos0 is true, otherwise dropped the oldest one.
+3. If the queue is full, drop qos0 messages if store_qos0 is true, otherwise drop the oldest one.
 
-The larger the inflight window size, the higher the throughput. The smaller the window size, the more strict the message order.
+The larger the inflight window size is, the higher the throughput is. The smaller the window size is, the more strict the message order is.
 
 PacketId and MessageId
 ----------------------
 
-The 16bits PacketId is defined by MQTT Protocol Specification, used by client/server to PUBLISH/PUBACK packets. A GUID(128bits globally unique Id) will be generated by the broker and assigned to a MQTT message.
+The 16-bit PacketId is defined by MQTT Protocol Specification, used by client/server to PUBLISH/PUBACK packets. A GUID(128-bit globally unique Id) will be generated by the broker and assigned to a MQTT message.
 
 Format of the globally unique message id::
 
@@ -146,17 +146,17 @@ The PacketId and MessageId in a End-to-End Message PubSub Sequence::
 PubSub Layer
 ------------
 
-The PubSub layer maintains a subscription table and responsible to dispatch MQTT messages to subscribers.
+The PubSub layer maintains a subscription table and is responsible to dispatch MQTT messages to subscribers.
 
 .. image:: _static/images/dispatch.png
 
-MQTT messages will be dispatched to the subscriber's session, which finally delivers the message to client.
+MQTT messages will be dispatched to the subscriber's session, which finally delivers the messages to client.
 
 -------------
 Routing Layer
 -------------
 
-The routing(distributed) layer maintains and replicates the global Topic Trie and Routing Table. The topic tire is composed of wildcard topics created by subscribers, and the Routing Table map a topic to nodes in the cluster.
+The routing(distributed) layer maintains and replicates the global Topic Trie and Routing Table. The topic tire is composed of wildcard topics created by subscribers. The Routing Table maps a topic to nodes in the cluster.
 
 For example, if node1 subscribed 't/+/x' and 't/+/y', node2 subscribed 't/#' and node3 subscribed 't/a', there will be a topic trie and route table::
 
@@ -173,11 +173,11 @@ For example, if node1 subscribed 't/+/x' and 't/+/y', node2 subscribed 't/#' and
     | t/a   -> node3        |
     -------------------------
 
-The routing layer would route MQTT messages between clustered nodes by topic trie match and routing table lookup:
+The routing layer would route MQTT messages among clustered nodes by topic trie match and routing table lookup:
 
 .. image:: _static/images/route.png
 
-The routing design follows the two rules:
+The routing design follows two rules:
 
 1. A message only gets forwarded to other cluster nodes if a cluster node is interested in it. This reduces the network traffic tremendously, because it prevents nodes from forwarding unnecessary messages.
 
@@ -307,7 +307,7 @@ emqttd_acl_internal implements the default ACL based on etc/acl.config file::
 Hooks Design
 ------------
 
-The emqttd broker implements a simple but powerful hooks mechanism to help users develop plugin. The broker would run the hooks when a client is connected/disconnected, a topic is subscribed/unsubscribed or a MQTT message is published/delivered/acked:
+The emqttd broker implements a simple but powerful hooks mechanism to help users develop plugin. The broker would run the hooks when a client is connected/disconnected, a topic is subscribed/unsubscribed or a MQTT message is published/delivered/acked.
 
 Hooks defined by the emqttd 1.0 broker:
 
@@ -331,7 +331,7 @@ Hooks defined by the emqttd 1.0 broker:
 | client.disconnected    | Run when client disconnected from broker             |
 +------------------------+------------------------------------------------------+
 
-The emqttd broker uses the `Chain-of-responsibility_pattern`_ to implement hook mechanism. The callback functions registered to hook will be executed one bye one::
+The emqttd broker uses the `Chain-of-responsibility_pattern`_ to implement hook mechanism. The callback functions registered to hook will be executed one by one::
 
                      --------  ok | {ok, NewAcc}   --------  ok | {ok, NewAcc}   --------
      (Args, Acc) --> | Fun1 | -------------------> | Fun2 | -------------------> | Fun3 | --> {ok, Acc} | {stop, Acc}
@@ -339,7 +339,7 @@ The emqttd broker uses the `Chain-of-responsibility_pattern`_ to implement hook
                         |                             |                             |
                    stop | {stop, NewAcc}         stop | {stop, NewAcc}         stop | {stop, NewAcc}
 
-The callback function for hook should return:
+The callback function for a hook should return:
 
 +-----------------+------------------------+
 | Return          | Description            |
@@ -353,7 +353,7 @@ The callback function for hook should return:
 | {stop, NewAcc}  | Return Acc and Break   |
 +-----------------+------------------------+
 
-The input arguments for a callback function is different depending on the type of hook. Clone the `emqttd_plugin_template`_ to check how to use hooks.
+The input arguments for a callback function are depending on the types of hook. Clone the `emqttd_plugin_template`_ project to check the argument in detail.
 
 Hook Implementation
 -------------------
@@ -396,7 +396,7 @@ And implemented in emqttd_hook module:
 Hook Usage
 ----------
 
-`emqttd_plugin_template`_ provides the examples for hook usage:
+The `emqttd_plugin_template`_ project provides the examples for hook usage:
 
 .. code:: erlang
 
@@ -434,7 +434,7 @@ Hook Usage
 Plugin Design
 -------------
 
-Plugin is a normal erlang application that could be started/stopped dynamically by a running emqttd broker.
+Plugin is a normal erlang application that can be started/stopped dynamically by a running emqttd broker.
 
 emqttd_plugins Module
 ---------------------