Update grammar in documentation (#139)

juhojama · web-flow · commit 74878f005371 · 2023-11-14T09:16:27.000+08:00
diff --git a/README.md b/README.md
@@ -10,9 +10,9 @@
 
 The framework that allows us to write PHP extensions using pure and safe Rust whenever possible.
 
-## Document & Tutorial
+## Documentation & Tutorial
 
-- Document: <https://docs.rs/phper>
+- Documentation: <https://docs.rs/phper>
 - Tutorial: <https://docs.rs/phper-doc/>
 
 ## Requirement
diff --git a/examples/http-server/src/request.rs b/examples/http-server/src/request.rs
@@ -42,7 +42,7 @@ pub fn make_request_class() -> ClassEntity<()> {
     class
 }
 
-/// New the object with class `HttpServer\HttpRequest`.
+/// Instantiate the object with class `HttpServer\HttpRequest`.
 pub fn new_request_object() -> phper::Result<StateObject<()>> {
     HTTP_REQUEST_CLASS.new_object([])
 }
diff --git a/examples/http-server/src/response.rs b/examples/http-server/src/response.rs
@@ -63,7 +63,7 @@ pub fn make_response_class() -> ClassEntity<Response<Body>> {
     class
 }
 
-/// New the object with class `HttpServer\HttpResponse`.
+/// Instantiate the object with class `HttpServer\HttpResponse`.
 pub fn new_response_object() -> phper::Result<StateObject<Response<Body>>> {
     HTTP_RESPONSE_CLASS.new_object([])
 }
diff --git a/phper-doc/doc/_01_introduction/index.md b/phper-doc/doc/_01_introduction/index.md
@@ -10,16 +10,16 @@ The crates are not only the PHP binding for Rust, but also the framework for wri
 
 ## Purpose
 
-I used to use C language to write PHP extensions. At that time, C/C++ are the only way to write PHP extensions.
+I used to use the C language to write PHP extensions. At that time, C and C++ were the only ways to write PHP extensions.
 
-But I found the problem is that using C language can easily cause memory problems, which is very troublesome when debugging PHP extensions.
+But I found the problem was that using the C language could easily cause memory problems, which were very troublesome when debugging PHP extensions.
 
-Moreover, third-party libraries in C language are not easy to use, and version compatibility problems are often encountered in dynamic linking, which is inconvenient to use.
+Moreover, third-party libraries in the C language are not easy to use, and version compatibility problems are often encountered in dynamic linking, which is inconvenient to use.
 
-Later, Rust appeared, and I started to use C to call Rust's FFI to develop PHP extensions. The experience is better than only use C language.
+Later, Rust appeared, and I started to use C to call Rust's FFI to develop PHP extensions. The experience was better than using only the C language.
 
-However, it is not convenient for Rust to generate C ABI and then call C, so I got the idea of using pure Rust to write PHP extensions.
+However, it was not convenient for Rust to generate C ABI and then call C, so I got the idea of using pure Rust to write PHP extensions.
 
-So I started to build the framework of phper.
+So I started building the framework for phper.
 
-The other goal is to enable PHP to benefit from the Rust ecosystem.
+Another goal is to enable PHP to benefit from the Rust ecosystem.
diff --git a/phper-doc/doc/_02_quick_start/_01_write_your_first_extension/index.md b/phper-doc/doc/_02_quick_start/_01_write_your_first_extension/index.md
@@ -38,7 +38,7 @@ Full example is <https://github.com/phper-framework/phper/tree/master/examples/h
    cargo add phper
    ```
 
-1. Create the `build.rs` ( Adapting MacOS ).
+1. Create the `build.rs` (adapting MacOS).
 
    ```rust,no_run
    fn main() {
@@ -50,7 +50,7 @@ Full example is <https://github.com/phper-framework/phper/tree/master/examples/h
    }
    ```
 
-1. Write these code in `src/lib.rs`.
+1. Add this code to `src/lib.rs`.
 
    ```rust
    use phper::{echo, functions::Argument, modules::Module, php_get_module, values::ZVal};
@@ -85,7 +85,7 @@ Full example is <https://github.com/phper-framework/phper/tree/master/examples/h
    }
    ```
 
-1. Build, if your php isn't installed globally, you should specify the path of `php-config`.
+1. Build, if your PHP isn't installed globally, you should specify the path of `php-config`.
 
    ```bash
    # Optional, specify if php isn't installed globally,
diff --git a/phper-doc/doc/_02_quick_start/_02_write_a_simple_http_client/index.md b/phper-doc/doc/_02_quick_start/_02_write_a_simple_http_client/index.md
@@ -1,9 +1,9 @@
 # Write a simple http client
 
-Here we will use Rust crate [reqwest](https://crates.io/crates/reqwest) to write a simple http client,
+Here we will use Rust crate [reqwest](https://crates.io/crates/reqwest) to write a simple HTTP client,
 like curl, but object-oriented.
 
-Full example is <https://github.com/phper-framework/phper/tree/master/examples/http-client>.
+Full example is at <https://github.com/phper-framework/phper/tree/master/examples/http-client>.
 
 Imagine that our PHP API should look like this:
 
@@ -31,7 +31,7 @@ var_dump([
 
 Here, the namespace of API is `HttpClient`.
 
-And there are three class:
+And there are three classes:
 
 - `HttpClientBuilder` is the builder of `HttpClient`.
 - `HttpClient` will send a http request and generate a http response.
@@ -73,7 +73,7 @@ Before writing the code, we first prepare the dependency and startup code.
    cargo add thiserror
    ```
 
-1. Create the `build.rs` ( Adapting MacOS ).
+1. Create the `build.rs` (adapting MacOS).
 
    ```rust,no_run
    fn main() {
@@ -245,7 +245,7 @@ Now let's begin to finish the logic.
 1. Register all classes in `src/lib.rs`.
 
 1. All codes are finished, so we can build the extension `.so`, and run the
-   php script of the beginning of the tutorial with the extension.
+   PHP script in the beginning of the tutorial with the extension.
 
    ```shell
    cargo build
diff --git a/phper-doc/doc/_03_integrate_with_pecl/index.md b/phper-doc/doc/_03_integrate_with_pecl/index.md
@@ -1,15 +1,10 @@
 # Integrate with PECL
 
-As can be seen from the `quick start` example, using phper to develop
-PHP extension doesn't need the `phpize` and `make` processes like developing
-with C/C++.
+As can be seen from the `quick start` example, using phper to develop a PHP extension doesn't require the `phpize` and `make` processes, as you would when developing with C/C++.
 
-But, if you want to publish the extension on [PECL](https://pecl.php.net/)
-(the official repository of PHP extensions), you need to integrate phper
-project with `phpize` and `make`, because PECL install command will call them.
+However, if you intend to publish the extension on PECL (the official repository of PHP extensions), you will need to integrate the phper project with `phpize` and `make` since the PECL install command will call them.
 
-This chapter will guide you how to integrate phper project with `pecl` and
-`phpize`.
+This chapter will guide you on how to integrate the phper project with `pecl` and `phpize`.
 
 ## Steps
 
diff --git a/phper-doc/doc/_04_zval/index.md b/phper-doc/doc/_04_zval/index.md
@@ -19,7 +19,7 @@ but there is only one type at a time, you can use
 The [`phper::values::ZVal`] implements a lot of [`std::convert::From`] for the
 conversion.
 
-Here is the mapping relationship of Rust type and base PHP type.
+Here is the mapping of relationships between Rust types and base PHP types.
 
 | Trait           | Rust type                   | PHP type |
 | --------------- | --------------------------- | -------- |
@@ -35,10 +35,10 @@ Here is the mapping relationship of Rust type and base PHP type.
 | `From<ZArray>`  | [`phper::arrays::ZArray`]   | array    |
 | `From<ZObject>` | [`phper::objects::ZObject`] | object   |
 
-Otherwise, there are also composite types that implement `From`.
+There are also composite types that implement `From`.
 
 - `From<Option<T>>`: if Some(T), T will be converted to PHP type like `From<T>`,
-  or `None` wll be converted to `null`.
+  or `None` will be converted to `null`.
 
 ```rust,no_run
 use phper::values::ZVal;
@@ -66,7 +66,7 @@ fn say_hello(arguments: &mut [ZVal]) -> phper::Result<()> {
     // str.
     let name = arguments[0].expect_z_str()?.to_str()?;
 
-    // Macro which do php internal `echo`.
+    // Macro which runs PHP internal function `echo`.
     echo!("Hello, {}!\n", name);
 
     Ok(())
@@ -80,22 +80,22 @@ The [`phper::values::ZVal`] both implements [`std::clone::Clone`] and
 
 - [`std::clone::Clone`]: represent value copy (Type ZObject is excluded because it is always passed by reference).
 
-- [`phper::alloc::RefClone`]: represent reference counting  copy (Type (), bool,
+- [`phper::alloc::RefClone`]: represent reference counting copy (Type (), bool,
   i64, f64 is excluded because they are not reference counting types).
 
 ## PHP internal cast
 
 > Refer to: <https://www.phpinternalsbook.com/php7/zvals/casts_and_operations.html#casts>
 
-PHP is a weakly typed language, supports type cast internally.
+PHP is a weakly typed language, yet it supports type casting internally.
 
 The zend engine provides `convert_to_*` functions to do the type cast, and
 `ZVal` wraps them directly.
 
 ## Callable
 
-The [`phper::values::ZVal`] can be call via [`phper::values::ZVal::call`], make
-sure the actual type is callable (string or array or closure).
+The [`phper::values::ZVal`] can be called via [`phper::values::ZVal::call`]. Make
+sure that the actual type is callable (string, array or closure).
 
 ```rust,no_run
 use phper::values::ZVal;
diff --git a/phper-doc/doc/_05_internal_types/_01_z_str/index.md b/phper-doc/doc/_05_internal_types/_01_z_str/index.md
@@ -5,11 +5,11 @@
 > Refer: <https://www.php.net/manual/en/language.types.string.php>
 
 The [`&ZStr`](phper::strings::ZStr) and [`ZString`](phper::strings::ZString) are
-the wrapper of [`zend_string`](phper::sys::zend_string).
+wrappers for [`zend_string`](phper::sys::zend_string).
 
 `ZStr` can be converted to `&[u8]`, `&CStr` and `&str`.
 
-`ZString` can be constructed from `impl AsRef<[u8]>`, has pair of `from_raw()`
+`ZString` can be constructed from `impl AsRef<[u8]>` and has pair of `from_raw()`
 and `into_raw()`, like in [`Box`].
 
 ```rust,no_run
@@ -38,7 +38,7 @@ let s = ZString::new("Hello world!");
 assert_eq!(s.to_str(), Ok("Hello world!"));
 ```
 
-`ZStr` implements `ToOwned`, can upgrade to `ZString` by value copy.
+`ZStr` implements `ToOwned`. It can upgrade to `ZString` by value copying.
 
 Because `zend_string` is reference counting type, so `ZStr` also implements
 [`ToRefOwned`](phper::alloc::ToRefOwned) (just like
@@ -56,12 +56,12 @@ extern "C" {
 
 let s = unsafe { ZStr::from_mut_ptr(something()) };
 
-// By value copy.
-let _s = s.to_owned(); 
+// By value copying.
+let _s = s.to_owned();
 
 // By refcount increment.
 let _s = s.to_ref_owned();
 ```
 
-Note that neither `ZStr` nor `ZString` implement `Send` and `Sync`, because PHP
+Note that neither `ZStr` nor `ZString` implements `Send` and `Sync`, because PHP
 is single-threaded.
diff --git a/phper-doc/doc/_05_internal_types/_02_z_arr/index.md b/phper-doc/doc/_05_internal_types/_02_z_arr/index.md
@@ -15,13 +15,13 @@
 *a list. I think it is a waste of performance.*
 
 The [`&ZArr`](phper::arrays::ZArr) and [`ZArray`](phper::arrays::ZArray) are
-the wrapper of [`zend_array`](phper::sys::zend_array) (same as `Hashtable`).
+the wrappers for [`zend_array`](phper::sys::zend_array) (same as `Hashtable`).
 
 [`&ZArr`](phper::arrays::ZArr) acts like [`HashMap`](std::collections::HashMap),
 also has api `insert()`, `get()`, `remove()`, but it's key type is
 [`Key`](phper::arrays::Key) and value type is [`ZVal`](phper::values::ZVal).
 
-Notice that phper prefer to use [`Symtables`](https://www.phpinternalsbook.com/php5/hashtables/array_api.html#symtables) api `zend_symtable_*`,
+Notice that phper prefers to use [`Symtables`](https://www.phpinternalsbook.com/php5/hashtables/array_api.html#symtables) api `zend_symtable_*`,
 so `get(42)` and `get("42")` should be considered the same.
 
 `ZArray` can be dereferenced to `ZArr`.
@@ -53,13 +53,13 @@ for (k, v) in arr.iter() {
 }
 ```
 
-`ZArr` implements `ToOwned`, can upgrade to `ZArray` by value copy via
+`ZArr` implements `ToOwned` and it can upgrade to `ZArray` by value copying via
 `zend_array_dup`.
 
-Because `zend_array` is reference counting type, so `ZArr` also implements
-[`ToRefOwned`](phper::alloc::ToRefOwned) (just like
-[`RefClone`](phper::alloc::RefClone) for [`ZVal`](phper::values::ZVal)), can
-upgrade to `ZArray` by refcount increment.
+Because `zend_array` is reference counting type, `ZArr` also implements
+[`ToRefOwned`](phper::alloc::ToRefOwned) (similar to
+[`RefClone`](phper::alloc::RefClone) for [`ZVal`](phper::values::ZVal)), allowing an
+upgrade to `ZArray` by incrementing the refcount.
 
 ```rust,no_run
 use phper::sys;
@@ -79,5 +79,5 @@ let _arr = arr.to_owned();
 let _arr = arr.to_ref_owned();
 ```
 
-Note that neither `ZArr` nor `ZArray` implement `Send` and `Sync`, because PHP
+Note that neither `ZArr` nor `ZArray` implements `Send` and `Sync`, because PHP
 is single-threaded.
diff --git a/phper-doc/doc/_05_internal_types/_03_z_obj/index.md b/phper-doc/doc/_05_internal_types/_03_z_obj/index.md
@@ -1,9 +1,9 @@
 # Z Obj
 
 The [`&ZObj`](phper::objects::ZObj) and [`ZObject`](phper::objects::ZObject) are
-the wrapper of [`zend_object`](phper::sys::zend_object).
+the wrappers for [`zend_object`](phper::sys::zend_object).
 
-You can do oop operation using `ZObj` or `ZObject`, like getting and setting properties,
+You can do OOP operation using `ZObj` or `ZObject`, like getting and setting properties,
 calling methods, etc.
 
 ```rust,no_run
@@ -36,5 +36,5 @@ let o = unsafe { ZObj::from_mut_ptr(something()) };
 let _o = o.to_ref_owned();
 ```
 
-Note that neither `ZObj` nor `ZObject` implement `Send` and `Sync`, because PHP
+Note that neither `ZObj` nor `ZObject` implements `Send` and `Sync`, because PHP
 is single-threaded.
diff --git a/phper-doc/doc/_05_internal_types/index.md b/phper-doc/doc/_05_internal_types/index.md
@@ -19,13 +19,13 @@ PHPER follows this design, there are the following types:
 - [ZObj](phper::objects::ZObj) / [ZObject](phper::objects::ZObject)
 
 > It seems that there is no need to separate into two types, but `ZStr`,
-> `ZArr`, and `ZObj` are all transparent types, so the fields of the struct
-> cannot be changed. Separating an ownership struct `ZString`, `ZArray`,
-> and `ZObject`, and then we can change fields of the struct in the future.
+> `ZArr`, and `ZObj` are all transparent types. Therefore, the fields of the struct
+> cannot be changed. Separating an ownership struct `ZString`, `ZArray`, and `ZObject`,
+> and then we can change fields of the struct in the future.
 
 ## Mapping relationship
 
-Here is the mapping relationship of Rust type and base PHP type.
+Here is the mapping of relationships between Rust types and base PHP types.
 
 | Rust type        | PHP type |
 | ---------------- | -------- |
diff --git a/phper-doc/doc/_06_module/_01_hooks/index.md b/phper-doc/doc/_06_module/_01_hooks/index.md
@@ -1,7 +1,7 @@
 # Hooks
 
-> PHP is a complex piece of machinery whose lifecycle really should be understood
-> by anyone who wants to understand how PHP operates.
+> PHP is a complex piece of machinery, and its lifecycle should be understood
+> by anyone who wants to grasp how PHP operates.
 >
 > Refer: <https://www.phpinternalsbook.com/php7/extensions_design/php_lifecycle.html>
 
@@ -10,10 +10,10 @@ PHP provides many hooks in lifecycle for extension to override.
 There are `MINIT`, `MSHUTDOWN`, `RINIT`, `RSHUTDOWN`, `GINIT`, `RSHUTDOWN`.
 
 Correspondingly, `PHPER` sets these hooks to complete some internal operations,
-such as registering extension information, registering functions, classes,
-constants, etc., but also exposes these hooks to users to overwrite.
+such as registering extension information, functions, classes, constants, etc.
+However, it also exposes these hooks to users for overwriting.
 
- The following is the corresponding relationship between PHP hooks and `Module`
+ The following presents the corresponding relationships between PHP hooks and `Module`
  methods:
 
 | PHP hooks | `Module` method                                          |
diff --git a/phper-doc/doc/_06_module/_02_register_functions/index.md b/phper-doc/doc/_06_module/_02_register_functions/index.md
@@ -25,7 +25,7 @@ pub fn get_module() -> Module {
 ```
 
 This example registers a function called `say_hello` and accepts a parameter 
-`name` passed by value, just like these codes in PHP:
+`name` passed by value, similarly in PHP:
 
 ```php
 <?php
@@ -54,7 +54,7 @@ Extension [ <persistent> extension #56 hello version <no_version> ] {
 It is useful to register the parameters of the function, which can limit the 
 number of parameters of the function.
 
-Especially, when the parameters need to be passed by reference.
+Especially when the parameters need to be passed by reference.
 
 ```rust,no_run
 use phper::{modules::Module, php_get_module, functions::Argument};
diff --git a/phper-doc/doc/_06_module/_04_register_ini_settings/index.md b/phper-doc/doc/_06_module/_04_register_ini_settings/index.md
@@ -26,7 +26,7 @@ About the policy of setting, you can refer to
 
 ## Configure ini settings
 
-The user can configure the ini settings in the `php.ini`. if not configure, the
+The user can configure the ini settings in the `php.ini`. If not configured, the
 configuration item will use the default value.
 
 ```ini
diff --git a/phper-doc/doc/_06_module/_06_register_class/index.md b/phper-doc/doc/_06_module/_06_register_class/index.md
@@ -2,7 +2,7 @@
 
 Registering classes is a bit more complicated than others.
 
-First, you have to new the class builder
+First, you have to instantiate the class builder
 [`ClassEntity`](phper::classes::ClassEntity), then register the parent class or
 implements interfaces, add the properties and methods, finally add it into the
 `Module`.
@@ -28,7 +28,7 @@ pub fn get_module() -> Module {
 }
 ```
 
-Just like these codes in PHP:
+Similarly in PHP:
 
 ```php
 <?php
diff --git a/phper-doc/doc/_06_module/_07_register_interface/index.md b/phper-doc/doc/_06_module/_07_register_interface/index.md
diff --git a/phper-doc/doc/_06_module/index.md b/phper-doc/doc/_06_module/index.md

Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ pub fn make_request_class() -> ClassEntity<()> {`
`42`	`42`	`class`
`43`	`43`	`}`
`44`	`44`
`45`		-/// New the object with class `HttpServer\HttpRequest`.
	`45`	+/// Instantiate the object with class `HttpServer\HttpRequest`.
`46`	`46`	`pub fn new_request_object() -> phper::Result<StateObject<()>> {`
`47`	`47`	`HTTP_REQUEST_CLASS.new_object([])`
`48`	`48`	`}`
Original file line number	Diff line number	Diff line change
`@@ -63,7 +63,7 @@ pub fn make_response_class() -> ClassEntity<Response<Body>> {`
`63`	`63`	`class`
`64`	`64`	`}`
`65`	`65`
`66`		-/// New the object with class `HttpServer\HttpResponse`.
	`66`	+/// Instantiate the object with class `HttpServer\HttpResponse`.
`67`	`67`	`pub fn new_response_object() -> phper::Result<StateObject<Response<Body>>> {`
`68`	`68`	`HTTP_RESPONSE_CLASS.new_object([])`
`69`	`69`	`}`