Merge pull request #27 from yassun7010/add_doc

Add doc

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml

@@ -0,0 +1,12 @@
+[book]
+authors = ["yassun7010"]
+language = "en"
+multilingual = false
+src = "src"
+title = "serde_valid"
+
+[output.html]
+no-section-label = true
+
+[output.html.fold]
+enable = true

docs/src/SUMMARY.md

@@ -0,0 +1,11 @@
+# Summary
+
+- [Installation](./install.md)
+- [usage](./usage/index.md)
+    - [**Validate**: single filed validation](./usage/validate.md)
+        - [maximum](./usage/validate/maximum.md)
+        - [minimum](./usage/validate/minimum.md)
+    - [**Rule**: multiple fileds validation](./usage/rule.md)
+    - [Nested validation](./usage/validate/nested.md)
+    - [Validate trailt](./usage/validate/trait.md)
+    - [Custom Message](./usage/custom_message.md)

docs/src/install.md

@@ -0,0 +1 @@
+# Installation

docs/src/usage/custom_message.md

@@ -0,0 +1,2 @@
+# Custom Message
+

docs/src/usage/index.md

@@ -0,0 +1 @@
+# Usage

docs/src/usage/rule.md

@@ -0,0 +1,85 @@
+# **Rule**: multiple fileds validation
+
+syn の v2 への移行に伴い、rule も下記のようなインターフェースに統一できないかを検討していました。
+
+```rust,ignore
+use serde_json::json;
+use serde_valid::Validate;
+
+fn sample_rule(_val1: &i32, _val2: &str) -> Result<(), serde_valid::validation::Error> {
+    Ok(())
+}
+
+#[derive(Validate)]
+#[rule(|s| sample_rule(s.val2, s.val1))]
+struct SampleStruct {
+    val1: String,
+    val2: i32,
+}
+
+let s = SampleStruct {
+    val1: "val1".to_owned(),
+    val2: 1,
+};
+
+assert!(s.validate().is_ok());
+```
+
+このコードは２つの点の問題を抱えています。
+
+### ルール関数の引数が参照ではなくなる。
+
+```rust,ignore
+fn sample_rule(_val1: i32, _val2: String) -> Result<(), serde_valid::validation::Error> {
+    Ok(())
+}
+```
+
+これは、実際にはより素晴らしい解決策かもしれません。
+常にクロージャに渡すことで、所有権の重複を回避することができるようです。
+（参照渡しをしていたのは、複数のカスタムバリデーションを用いる際にコピーを持たないフィールドでは所有権の問題に遭遇する為です）。
+
+この思わぬ効果は、より自然なカスタムバリデーションを書くことができるようになります。
+しかし、全てをクロージャに包む場合、関数が都度生成されるため、バイナリサイズやパフォーマンスに影響が出る可能性があります。
+
+あぁ、実験を続けると、クロージャでも所有権の問題が出てきました。やはり、参照渡しにする必要がありました。
+もしくは、 Copy トレイトがあることを syn の段階で理解する必要があります。
+
+### クロージャの引数の型を指定しないといけない。
+実際には、こう書かねばコンパイルに失敗します。
+
+```rust,ignore
+#[derive(Validate)]
+#[rule(|s: &Self| sample_rule(&s.val2, &s.val1))]
+struct SampleStruct {
+    val1: String,
+    val2: i32,
+}
+```
+
+これはかなり冗長です。
+
+### 将来的には custom との統一
+
+構造体を引数としたクロージャを書けることにより、 rule は custom と同じインターフェースになります。
+
+
+```rust,ignore
+fn sample_rule(val1: &SampleStruct) -> Result<(), serde_valid::validation::Error> {
+    Ok(())
+}
+
+#[derive(Validate)]
+#[rule(sample_rule)]
+struct SampleStruct {
+    val1: String,
+    val2: i32,
+}
+```
+
+その場合、 rule を用意する理由はありません。
+
+上の問題を上手く解決できた場合、 rule は非推奨になるでしょう。
+
+一旦、クロージャへの対応に関して、特別なロジックを追加しました。
+こちらの方が既存の実装を利用して作成しやすかった為です。

docs/src/usage/validate.md

@@ -0,0 +1 @@
+# Validate: single filed validation

docs/src/usage/validate/maximum.md

@@ -0,0 +1,16 @@
+# #[validate(maximum)]
+
+```rust
+# extern crate serde_valid;
+use serde_valid::Validate;
+
+#[derive(Validate)]
+struct SampleStruct {
+    #[validate(maximum = 6)]
+    val: i32,
+}
+
+assert!(SampleStruct { val: 5 }.validate().is_ok());
+assert!(SampleStruct { val: 6 }.validate().is_ok());
+assert!(SampleStruct { val: 7 }.validate().is_err());
+```

docs/src/usage/validate/minimum.md

@@ -0,0 +1 @@
+# #[validate(minimum)]

docs/src/usage/validate/nested.md

@@ -0,0 +1,28 @@
+# Nested validation
+
+To validate nested structures, add the #[validate] attribute to the target field.
+
+```rust
+# extern crate serde_valid;
+use serde_valid::Validate;
+
+#[derive(Validate)]
+struct ParentStruct {
+    #[validate] // <--- Add #[validate] attribute to the nested type field!
+    nested: ChildStruct,
+}
+
+#[derive(Validate)]
+struct ChildStruct {
+    #[validate(maximum = 6)]
+    val: i32,
+}
+
+assert!(
+    ParentStruct {
+        nested: ChildStruct{
+            val: 5
+        }
+    }.validate().is_ok()
+);
+```

docs/src/usage/validate/trait.md

@@ -0,0 +1 @@
+# Validate trailt

scripts/doctest.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+set -e
+
+cd "$(dirname "$0")/../docs"
+
+mdbook test --library-path ../target/debug/deps

serde_valid.code-workspace

@@ -4,6 +4,10 @@
             "name": "root",
             "path": "."
         },
+        {
+            "name": "docs",
+            "path": "docs",
+        },
         {
             "name": "axum_serde_valid",
             "path": "axum_serde_valid"
@@ -30,4 +34,4 @@
             "tamasfe.even-better-toml"
         ]
     }
-}
+}