Fix types and remove outdated doc

Author: frostyplanet

docs/client_macros.md

@@ -5,8 +5,8 @@ The `#[client_task_enum]` and `#[client_task]` procedural macro simplifies the i
 `#[client_task]` attribute allows users to define a struct representing an RPC task and specify its common fields, request, response, and optional blob data using `#[field(...)]` attributes.
 It will not generate ClientTask trait because the ClientTaskAction is optional for task variants.
 
-`#[client_task_enum]` attribute allow user to wrap an enum and delegate the ClienTask trait requirements to it's variants.
-It will generate ClientTask trait and the ClientTaskAction according to #[action()] specified for enum variants.
+`#[client_task_enum]` attribute allows users to wrap an enum and delegate the ClientTask trait requirements to its variants.
+It will generate the ClientTask trait and the ClientTaskAction according to the #[action()] specified for enum variants.
 
 ### `#[action]` on enum variants
 
@@ -30,7 +30,7 @@ pub enum FileTask {
     Close(FileCloseTask),
 }
 
-// This task does not need to specify an action, as it's handled by the enum variant.
+// This task does not need to specify an action, as it is handled by the enum variant.
 #[client_task]
 pub struct FileOpenTask {
     #[field(common)]
@@ -73,12 +73,12 @@ The macro processes specific fields within the task struct based on the `#[field
     *   **Requirements:** This field is mandatory. The macro generates `Deref` and `DerefMut` implementations for the task struct, delegating to this `common` field. This allows direct access to the common fields of the task struct.
 
 *   `#[field(action)]`
-    *   Purpose: implement ClientTaskAction trait to return RpcAction according to the field
-    *   Requirements: there's no `action=` specified within the client_task attribute. the field is a numeric or string type, or an enum type that repr by number.
+    *   Purpose: Implement the ClientTaskAction trait to return an RpcAction according to the field.
+    *   Requirements: There is no `action=` specified within the `client_task` attribute. The field is a numeric or string type, or an enum type that is represented by a number.
 
-*   attribute parameter action in `#[client_task(action=...)]`
-    *   Purpose: implement ClientTaskAction trait with a static value
-    *   Requirements: there's no `#[field(action)]` specified within the struct.  `action()` parameter must be only one, can be numeric, or string, or an enum repr by number.
+*   attribute parameter `action` in `#[client_task(action=...)]`
+    *   Purpose: Implement the ClientTaskAction trait with a static value.
+    *   Requirements: There is no `#[field(action)]` specified within the struct. The `action()` parameter must be only one, and can be numeric, a string, or an enum represented by a number.
 
 *   `#[field(req)]`:
     *   **Purpose:** Designates the field containing the request payload for the RPC call.
@@ -112,11 +112,11 @@ The `#[client_task]` macro automatically generates the following trait implement
 
 *   `ClientTaskEncode`:
     *   `encode_req<C: occams_rpc::codec::Codec>(&self, codec: &C) -> Result<Vec<u8>, ()>`: Encodes the content of the `#[field(req)]` field using the provided codec.
-    *   `get_req_blob(&self) -> Option<&[u8]>`: If `#[field(req_blob)]` is present, returns `Some` reference to the blob data; otherwise, it returns `None`.
+    *   `get_req_blob(&self) -> Option<&[u8]>`: If `#[field(req_blob)]` is present, returns a `Some` reference to the blob data; otherwise, it returns `None`.
 
 *   `ClientTaskDecode`:
     *   `decode_resp<C: occams_rpc::codec::Codec>(&mut self, codec: &C, buffer: &[u8]) -> Result<(), ()>`: Decodes the response buffer using the provided codec and stores the result in the `#[field(resp)]` field.
-    *   `get_resp_blob_mut(&mut self) -> Option<&mut impl occams_rpc::io::AllocateBuf>`: If `#[field(resp_blob)]` is present, returns `Some` mutable reference to the response blob `Option<T>`; otherwise, it returns `None`.
+    *   `get_resp_blob_mut(&mut self) -> Option<&mut impl occams_rpc::io::AllocateBuf>`: If `#[field(resp_blob)]` is present, returns a `Some` mutable reference to the response blob `Option<T>`; otherwise, it returns `None`.
 
 *   `ClientTaskDone`:
     *   This trait is implemented when `#[field(res)]` and `#[field(noti)]` are present.
@@ -131,7 +131,7 @@ The `#[client_task]` macro automatically generates the following trait implement
     }
     ```
 
-*   when `#[client_task(debug)]` is specified, you will get a more specified Debug generated according to `req` and `resp` field
+*   when `#[client_task(debug)]` is specified, you will get a more specific Debug generated according to the `req` and `resp` fields
     ```rust
     impl std::fmt::Debug for T {
         fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
@@ -145,7 +145,7 @@ The `#[client_task]` macro automatically generates the following trait implement
     ```
 
 
-The `#[client_task_enum]` will implement `From` to assist convertion from it's variants to parent enum, and delegating `ClienTaskEnode`, `ClientTaskDecode`, `ClientTaskAction`, `RpcClientTask` to it's variants.
+The `#[client_task_enum]` will implement `From` to assist conversion from its variants to the parent enum, and delegate `ClientTaskEncode`, `ClientTaskDecode`, `ClientTaskAction`, and `RpcClientTask` to its variants.
 
 ## User Responsibilities
 

docs/client_task_v1.md

@@ -2,15 +2,15 @@
 
 ## Design goal
 
-A modular, plugable RPC that supports various async runtimes.
+A modular, pluggable RPC that supports various async runtimes.
 
 * interface types:
   - stream: Interface for stream processing.
   - api: Interface for remote function call.
 * transport types:
   - TCP transport: optimized for high throughput internal network.
   - RDMA transport: optimized for low latency internal network.
-  - Quic transport: optimized for high throughput public network.
+  - QUIC transport: optimized for high throughput public network.
 * codec:
   - Msgpack
   - bincode
@@ -22,13 +22,13 @@ A modular, plugable RPC that supports various async runtimes.
 
 ### Stream protocol
 
-str/stream/proto.rs: Defines general proto
+src/stream/proto.rs: Defines general proto
 
-`RpcAction`: numeric action is for fewer type variants, while string action is for the implmentation of API interface.
+`RpcAction`: A numeric action is for fewer type variants, while a string action is for the implementation of the API interface.
 
-Request format: each request package has a fixed-length header (ReqHead), then followed by structured encoded "msg", then optionally followed by a "blob" (which allocated as owned buffer).
+Request format: Each request package has a fixed-length header (ReqHead), followed by a structured encoded "msg", and then optionally followed by a "blob" (which is allocated as an owned buffer).
 
-Response format: each reponse package has a fixed-length header (RespHead), then followed by structured encoded "msg", then optionally followed by a "blob" (which allocated as owned buffer)
+Response format: Each response package has a fixed-length header (RespHead), followed by a structured encoded "msg", and then optionally followed by a "blob" (which is allocated as an owned buffer)
 
 ### Stream Client
 
@@ -37,63 +37,59 @@ Response format: each reponse package has a fixed-length header (RespHead), then
 
 src/stream/server.rs:
 
-`ServerFactory` is the interafce for user can assign or customize with various plugin (transport, codec, ...)
+`ServerFactory` is the interface for a user to assign or customize with various plugins (transport, codec, etc.).
 
 src/stream/server_impl.rs:
 
-`RpcServer` is the server implementation, listen and accept connections through transport. The new connection is process by ServerHandle::run interface. We typically use the `ServerHandleTaskStream` implmentation, which utilizes a coroutine to read and a coroutine to write, so that the throughput can at max use 2 cpu cores with one connection.
+`RpcServer` is the server implementation, which listens for and accepts connections through the transport. The new connection is processed by the ServerHandle::run interface. We typically use the `ServerHandleTaskStream` implementation, which utilizes a coroutine to read and a coroutine to write, so that the throughput can use at most 2 CPU cores with one connection.
 
-We intended to support service-level graceful restart and graceful shutdown.
+We intend to support service-level graceful restart and graceful shutdown.
 
-As a packet received by server, should have gone through the steps:
+A packet received by the server should have gone through the following steps:
 
     decode -> request task -> dispatch -> processed -> response task -> encode -> write
 
 #### decode
 
-An enum task should impl ServerTaskDecode::decode_req(action ... ), regconize sub task type by RpcAction.
+An enum task should implement ServerTaskDecode::decode_req(action ... ), and recognize the sub-task type by RpcAction.
 
-For numeric, more used in the stream interface, suitable to use a generated match to call the sub types decode_req.
+For numeric actions, which are more used in the stream interface, it is suitable to use a generated match to call the sub-type's decode_req.
 
 The macro can be:
 
 ```
 
 #[server_task_enum]
 pub enum MyServerTask {
-    [action=xxx]
+    #[action=xxx]
     Type1(SubType1)
-    [action=xxx]
+    #[action=xxx]
     Type2(SubType2)
 }
 ```
 
-(action may be num or "string")
+(action may be a number or a string)
 
-For SubType1, need to generate MyServerTask::From SubType1. If user process using SubType, and call subtype::set_result(), should transform into() the supertype to call RpcRespNoti.done().
+For SubType1, we need to generate MyServerTask::From<SubType1>. If a user processes using SubType and calls subtype::set_result(), it should be transformed via into() into the supertype to call RpcRespNoti.done().
 
-If user use the ServerTaskVariant/ServerTaskVariantFull generic as subtype, which already implemented ServerTaskEncode/Encode,
- they cannot impl they own method due to the "Orphan Rule" limitation of Rust,
- they should impl wrapper types with new-type pattern. (It's not certain for me Deref, should test)
+If a user uses the ServerTaskVariant/ServerTaskVariantFull generic as a subtype, which has already implemented ServerTaskEncode/Encode, they cannot implement their own methods due to the "Orphan Rule" limitation of Rust. They should implement wrapper types with the new-type pattern. (I'm not certain about Deref, I should test it).
 
 So the macro is on MyServerTask:
 
-* Need to assign action for the variants for ServerTaskDecode::decode_req, provides get_action(&self) for user
+* Need to assign an action for the variants for ServerTaskDecode::decode_req, which provides get_action(&self) for the user
 
-* Need to impl From variants
+* Need to implement From for variants
 
-For string, might used in the API interface, can be first match in a HashMap to decide which class to handle, an decode accoding to string (class::method) to a specified Req type.
+For a string, which might be used in the API interface, it can be first matched in a HashMap to decide which class to handle, and decoded according to the string (class::method) to a specified Req type.
 
 
 #### Dispatch
 
-The dispatcher is repsponsible for decode the task and dispatch to backend processing. (There may be struct like worker pool in other threads/coroutines to handle)
+The dispatcher is responsible for decoding the task and dispatching it to the backend for processing. (There may be a struct like a worker pool in other threads/coroutines to handle this).
 
-Codec is intend to support encryption, so there should be shared state, need to initialized as Arc<Codec> share between
-conn reader and writer. Therefore, The dispatcher should be a Arc being shared between reader and writer.
+The codec is intended to support encryption, so there should be a shared state, which needs to be initialized as an Arc<Codec> and shared between the connection reader and writer. Therefore, the dispatcher should be an Arc shared between the reader and writer.
 
-Because the connection of reader and writer is parallel, we should define ReqDispatch trait and RespReceiver trait separately. The ReqDispatch relies on RespReceiver because it should know about the task type of done channel.
+Because the reader and writer for a connection are parallel, we should define the ReqDispatch and RespReceiver traits separately. The ReqDispatch trait relies on RespReceiver because it needs to know about the task type of the done channel.
 
-We set RespReceiver in ServerFactory as an associate type. but we leave the ReqDispatch to be infered From
-` fn new_dispatcher(&self) -> impl ReqDispatch<Self::RespReceiver>``, because like TaskReqDispatch, usually comes with
-closure capturing the connext about how to dispatch the task. There may be a Fn or a struct defined by user.
+We set RespReceiver in ServerFactory as an associated type, but we leave ReqDispatch to be inferred from
+` fn new_dispatcher(&self) -> impl ReqDispatch<Self::RespReceiver>``, because, like TaskReqDispatch, it usually comes with a closure capturing the context about how to dispatch the task. This may be a Fn or a struct defined by the user.

docs/design_v2.md

@@ -49,15 +49,15 @@ pub enum ServerTask {
     Task1(SubTask1),
 }
 
-#[server_task_enum(resp)] // Example with only resp, resp_type and action is not required
+#[server_task_enum(resp)] // Example with only resp, resp_type and action are not required
 #[derive(Debug)]
 pub enum ServerTask {
     Task1(SubTask1),
 }
 ```
 
-The `#[action()]` can contain multiple items, separated with comma. Then it will call the SubType::decode_req in multiple situtation.
-In this case the SubType is required to impl `ServerTaskAction` trait to return the actual action it stored
+The `#[action()]` can contain multiple items, separated by a comma. It will then call SubType::decode_req in multiple situations.
+In this case, the SubType is required to implement the `ServerTaskAction` trait to return the actual action it stored.
 
 ```rust
 #[server_task_enum(req, resp_type = RpcResp)] // Example with only req, resp_type is required
@@ -72,7 +72,7 @@ pub struct SubTask1 {
     ...
 }
 
-When the `#[action()]` item is not numeric, nor string, it can be an one or multiple Enum value, in this case the value conver to number when parsing.
+When an `#[action()]` item is not numeric or a string, it can be one or more Enum values. In this case, the value is converted to a number when parsing.
 
 ``` rust
 #[server_task_enum(req, resp_type = RpcResp)] // Example with only req, resp_type is required

docs/server_macros.md

@@ -35,7 +35,7 @@ pub fn write_pid_file(run_dir: &str, prog_name: &str) -> std::io::Result<()> {
     Ok(())
 }
 
-/// Call after program is fork. Use a seperate empty file to notify parent that child has started up.
+/// Call after program is fork. Use a separate empty file to notify parent that child has started up.
 fn write_child_pid_file(run_dir: &str, prog_name: &str) -> std::io::Result<()> {
     let pid_file_path = Path::new(run_dir).join(format!("{}_{}", prog_name, process::id()));
     std::fs::File::create(pid_file_path.to_str().unwrap())?;