Write documents.

jmjoy · jmjoy · commit e57334b28cd6 · 2021-04-30T11:09:40.000+08:00
diff --git a/examples/hello/README.md b/examples/hello/README.md
@@ -26,3 +26,7 @@ cargo test --release
 ```bash
 cargo run --release -- install
 ```
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
diff --git a/examples/log/README.md b/examples/log/README.md
@@ -26,3 +26,7 @@ cargo test --release
 ```bash
 cargo run --release -- install
 ```
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
diff --git a/examples/log/tests/integration.rs b/examples/log/tests/integration.rs
@@ -1,26 +1,25 @@
 use phper_test::test_php_scripts_with_condition;
 use std::{env, path::Path, str};
+use std::process::Output;
 
 #[test]
 fn test_php() {
+    let base_dir = Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("tests")
+        .join("php");
+
     test_php_scripts_with_condition(
         env!("CARGO_BIN_EXE_log"),
         &[
             (
-                &Path::new(env!("CARGO_MANIFEST_DIR"))
-                    .join("tests")
-                    .join("php")
-                    .join("test_php_say.php"),
+                &base_dir.join("test_php_say.php"),
                 &|output| {
                     let stdout = str::from_utf8(&output.stdout).unwrap();
                     stdout == "Hello, world!" && output.status.success()
                 },
             ),
             (
-                &Path::new(env!("CARGO_MANIFEST_DIR"))
-                    .join("tests")
-                    .join("php")
-                    .join("test_php_notice.php"),
+                &base_dir.join("test_php_notice.php"),
                 &|output| {
                     let stdout = str::from_utf8(&output.stdout).unwrap();
                     stdout.contains("Notice:")
@@ -29,10 +28,7 @@ fn test_php() {
                 },
             ),
             (
-                &Path::new(env!("CARGO_MANIFEST_DIR"))
-                    .join("tests")
-                    .join("php")
-                    .join("test_php_warning.php"),
+                &base_dir.join("test_php_warning.php"),
                 &|output| {
                     let stdout = str::from_utf8(&output.stdout).unwrap();
                     stdout.contains("Warning:")
@@ -41,21 +37,15 @@ fn test_php() {
                 },
             ),
             (
-                &Path::new(env!("CARGO_MANIFEST_DIR"))
-                    .join("tests")
-                    .join("php")
-                    .join("test_php_error.php"),
+                &base_dir.join("test_php_error.php"),
                 &|output| {
                     let stdout = str::from_utf8(&output.stdout).unwrap();
                     stdout.contains("Fatal error:")
                         && stdout.contains("Something gone failed: just for test")
                 },
             ),
             (
-                &Path::new(env!("CARGO_MANIFEST_DIR"))
-                    .join("tests")
-                    .join("php")
-                    .join("test_php_deprecated.php"),
+                &base_dir.join("test_php_deprecated.php"),
                 &|output| {
                     let stdout = str::from_utf8(&output.stdout).unwrap();
                     stdout.contains("Deprecated:")
diff --git a/phper-alloc/README.md b/phper-alloc/README.md
@@ -1,3 +1,7 @@
 # phper-alloc
 
-Alloc related items for phper crate.
+Alloc related items for [phper](https://crates.io/crates/phper).
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
diff --git a/phper-alloc/src/lib.rs b/phper-alloc/src/lib.rs
@@ -1,4 +1,11 @@
 #![warn(rust_2018_idioms, clippy::dbg_macro, clippy::print_stdout)]
+/*!
+Alloc related items for [phper](https://crates.io/crates/phper).
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
+*/
 
 /// The Box which use php `emalloc` and `efree` to manage memory.
 ///
diff --git a/phper-build/README.md b/phper-build/README.md
@@ -1,3 +1,9 @@
 # phper-build
 
-Generates stubs for project using phper.
+Generate stubs for project using [phper](https://crates.io/crates/phper).
+
+Add this crate in your `[build-dependencies]` and using in `build.rs`.
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
diff --git a/phper-build/src/lib.rs b/phper-build/src/lib.rs
@@ -1,3 +1,15 @@
+#![warn(rust_2018_idioms, clippy::dbg_macro, clippy::print_stdout)]
+
+/*!
+Generate stubs for project using [phper](https://crates.io/crates/phper).
+
+Add this crate in your `[build-dependencies]` and using in `build.rs`.
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
+*/
+
 use phper_sys::{PHP_DEBUG, PHP_MAJOR_VERSION, PHP_MINOR_VERSION, PHP_RELEASE_VERSION, USING_ZTS};
 
 /// Register useful rust cfg for project using phper.
diff --git a/phper-macros/README.md b/phper-macros/README.md
@@ -1,3 +1,7 @@
 # phper-macros
 
-The proc-macros for phper crate.
+The proc-macros for [phper](https://crates.io/crates/phper).
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
diff --git a/phper-macros/src/lib.rs b/phper-macros/src/lib.rs
@@ -1,3 +1,13 @@
+#![warn(rust_2018_idioms, clippy::dbg_macro, clippy::print_stdout)]
+
+/*!
+The proc-macros for [phper](https://crates.io/crates/phper).
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
+*/
+
 mod alloc;
 mod inner;
 mod log;
diff --git a/phper-sys/README.md b/phper-sys/README.md
@@ -1,3 +1,9 @@
 # phper-sys
 
 Low level PHP binding for Rust.
+
+The php-config is needed. You can set environment `PHP_CONFIG` to specify the path.
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
diff --git a/phper-sys/src/lib.rs b/phper-sys/src/lib.rs
@@ -1,7 +1,18 @@
+#![warn(rust_2018_idioms, clippy::dbg_macro, clippy::print_stdout)]
 #![allow(non_upper_case_globals)]
 #![allow(non_camel_case_types)]
 #![allow(non_snake_case)]
 
+/*!
+Low level PHP binding for Rust.
+
+The php-config is needed. You can set environment `PHP_CONFIG` to specify the path.
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
+*/
+
 use std::os::raw::c_char;
 
 include!(concat!(env!("OUT_DIR"), "/php_bindings.rs"));
diff --git a/phper-test/README.md b/phper-test/README.md
@@ -1,3 +1,9 @@
 # phper-test
 
-PHPer testing utilities.
+Integration test tool for [phper](https://crates.io/crates/phper).
+
+The `php-config` is needed. You can set environment `PHP_CONFIG` to specify the path.
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
diff --git a/phper-test/src/lib.rs b/phper-test/src/lib.rs
@@ -1,3 +1,15 @@
+#![warn(rust_2018_idioms, clippy::dbg_macro, clippy::print_stdout)]
+
+/*!
+Integration test tool for [phper](https://crates.io/crates/phper).
+
+The `php-config` is needed. You can set environment `PHP_CONFIG` to specify the path.
+
+## License
+
+[Unlicense](https://github.com/jmjoy/phper/blob/master/LICENSE).
+!*/
+
 use once_cell::sync::OnceCell;
 use std::{
     env,
@@ -10,6 +22,14 @@ use std::{
 };
 use tempfile::NamedTempFile;
 
+/// Check your extension by executing the php script, if the all executing return success, than the test is pass.
+///
+/// - `exec_path` is the path of the make executable, which will be used to detect the path of
+/// extension lib.
+///
+/// - `scripts` is the path of your php test scripts.
+///
+/// See [example hello integration test](https://github.com/jmjoy/phper/blob/master/examples/hello/tests/integration.rs).
 pub fn test_php_scripts(exe_path: impl AsRef<Path>, scripts: &[&dyn AsRef<Path>]) {
     let condition = |output: Output| output.status.success();
     let scripts = scripts
@@ -19,6 +39,14 @@ pub fn test_php_scripts(exe_path: impl AsRef<Path>, scripts: &[&dyn AsRef<Path>]
     test_php_scripts_with_condition(exe_path, &*scripts);
 }
 
+/// Check your extension by executing the php script, if the all your specified checkers are pass, than the test is pass.
+///
+/// - `exec_path` is the path of the make executable, which will be used to detect the path of
+/// extension lib.
+///
+/// - `scripts` is the slice of the tuple, format is `(path of your php test script, checker function or closure)`.
+///
+/// See [example log integration test](https://github.com/jmjoy/phper/blob/master/examples/log/tests/integration.rs).
 pub fn test_php_scripts_with_condition(
     exe_path: impl AsRef<Path>,
     scripts: &[(&dyn AsRef<Path>, &dyn Fn(Output) -> bool)],
