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

Improve documentation for custom functions

Author: Dean Karn

_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.StructField())     // by passing alt name to ReportError like below
+			fmt.Println(err.StructNamespace())
+			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.Field())
-			fmt.Println(err.StructNamespace()) // can differ when a custom TagNameFunc is registered or
-			fmt.Println(err.StructField())     // by passing alt name to ReportError like below
+			fmt.Println(err.Namespace()) // can differ when a custom TagNameFunc is registered or
+			fmt.Println(err.Field())     // by passing alt name to ReportError like below
+			fmt.Println(err.StructNamespace())
+			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.LastName, "LastName", "lname", "fnameorlname", "")
+		sl.ReportError(user.FirstName, "fname", "FirstName", "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.
-See below examples of registration and use.
+A non standard validator must be registered manually like you would
+with your own custom validation functions.
+
+Example of registration and use:
 
 	type Test struct {
 		TestField string `validate:"yourtag"`
@@ -1089,13 +1076,30 @@ 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.
 		For strings ensures they do not contain only spaces. For channels, maps, slices and arrays
 		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