Merge pull request #530 from skateinmars/chore/improve-doc

Improve documentation for custom functions

_examples/simple/main.go

@@ -68,8 +68,8 @@ func validateStruct() {
 
 			fmt.Println(err.Namespace())
 			fmt.Println(err.Field())
-			fmt.Println(err.StructNamespace()) // can differ when a custom TagNameFunc is registered or
+			fmt.Println(err.StructNamespace())
-			fmt.Println(err.StructField())     // by passing alt name to ReportError like below
+			fmt.Println(err.StructField())
 			fmt.Println(err.Tag())
 			fmt.Println(err.ActualTag())
 			fmt.Println(err.Kind())

_examples/struct-level/main.go

@@ -2,6 +2,8 @@ package main
 
 import (
 	"fmt"
+	"reflect"
+	"strings"
 
 	"gopkg.in/go-playground/validator.v9"
 )
@@ -11,7 +13,7 @@ type User struct {
 	FirstName      string     `json:"fname"`
 	LastName       string     `json:"lname"`
 	Age            uint8      `validate:"gte=0,lte=130"`
-	Email          string     `validate:"required,email"`
+	Email          string     `json:"e-mail" validate:"required,email"`
 	FavouriteColor string     `validate:"hexcolor|rgb|rgba"`
 	Addresses      []*Address `validate:"required,dive,required"` // a person can have a home and cottage...
 }
@@ -31,6 +33,15 @@ func main() {
 
 	validate = validator.New()
 
+	// register function to get tag name from json tags.
+	validate.RegisterTagNameFunc(func(fld reflect.StructField) string {
+		name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
+		if name == "-" {
+			return ""
+		}
+		return name
+	})
+
 	// register validation for 'User'
 	// NOTE: only have to register a non-pointer type for 'User', validator
 	// interanlly dereferences during it's type checks.
@@ -48,7 +59,7 @@ func main() {
 		FirstName:      "",
 		LastName:       "",
 		Age:            45,
-		Email:          "Badger.Smith@gmail.com",
+		Email:          "Badger.Smith@gmail",
 		FavouriteColor: "#000",
 		Addresses:      []*Address{address},
 	}
@@ -67,10 +78,10 @@ func main() {
 
 		for _, err := range err.(validator.ValidationErrors) {
 
-			fmt.Println(err.Namespace())
+			fmt.Println(err.Namespace()) // can differ when a custom TagNameFunc is registered or
-			fmt.Println(err.Field())
+			fmt.Println(err.Field())     // by passing alt name to ReportError like below
-			fmt.Println(err.StructNamespace()) // can differ when a custom TagNameFunc is registered or
+			fmt.Println(err.StructNamespace())
-			fmt.Println(err.StructField())     // by passing alt name to ReportError like below
+			fmt.Println(err.StructField())
 			fmt.Println(err.Tag())
 			fmt.Println(err.ActualTag())
 			fmt.Println(err.Kind())
@@ -101,8 +112,8 @@ func UserStructLevelValidation(sl validator.StructLevel) {
 	user := sl.Current().Interface().(User)
 
 	if len(user.FirstName) == 0 && len(user.LastName) == 0 {
-		sl.ReportError(user.FirstName, "FirstName", "fname", "fnameorlname", "")
+		sl.ReportError(user.FirstName, "fname", "FirstName", "fnameorlname", "")
-		sl.ReportError(user.LastName, "LastName", "lname", "fnameorlname", "")
+		sl.ReportError(user.LastName, "lname", "LastName", "fnameorlname", "")
 	}
 
 	// plus can do more, even with different tag than "fnameorlname"

doc.go

@@ -1058,27 +1058,14 @@ Validator notes:
 		And the best reason, you can submit a pull request and we can keep on
 		adding to the validation library of this package!
 
-Panics
-
-This package panics when bad input is provided, this is by design, bad code like
-that should not make it to production.
-
-	type Test struct {
-		TestField string `validate:"nonexistantfunction=1"`
-	}
-
-	t := &Test{
-		TestField: "Test"
-	}
-
-	validate.Struct(t) // this will panic
-
 Non standard validators
 
 A collection of validation rules that are frequently needed but are more
 complex than the ones found in the baked in validators.
-A non standard validator must be registered manually using any tag you like.
+A non standard validator must be registered manually like you would
-See below examples of registration and use.
+with your own custom validation functions.
+
+Example of registration and use:
 
 	type Test struct {
 		TestField string `validate:"yourtag"`
@@ -1089,7 +1076,9 @@ See below examples of registration and use.
 	}
 
 	validate := validator.New()
-	validate.RegisterValidation("yourtag", validations.ValidatorName)
+	validate.RegisterValidation("yourtag", validators.NotBlank)
+
+Here is a list of the current non standard validators:
 
 	NotBlank
 		This validates that the value is not blank or with length zero.
@@ -1097,5 +1086,20 @@ See below examples of registration and use.
 		ensures they don't have zero length. For others, a non empty value is required.
 
 		Usage: notblank
+
+Panics
+
+This package panics when bad input is provided, this is by design, bad code like
+that should not make it to production.
+
+	type Test struct {
+		TestField string `validate:"nonexistantfunction=1"`
+	}
+
+	t := &Test{
+		TestField: "Test"
+	}
+
+	validate.Struct(t) // this will panic
 */
 package validator