Merge pull request #304 from aaronlehmann/doc-fixes

Documentation fixes

baked_in.go

@@ -11,10 +11,12 @@ import (
 	"unicode/utf8"
 )
 
-// Func accepts a FieldLevel interface for all validation needs
+// Func accepts a FieldLevel interface for all validation needs. The return
+// value should be true when validation succeeds.
 type Func func(fl FieldLevel) bool
 
-// FuncCtx accepts a context.Context and FieldLevel interface for all validation needs
+// FuncCtx accepts a context.Context and FieldLevel interface for all
+// validation needs. The return value should be true when validation succeeds.
 type FuncCtx func(ctx context.Context, fl FieldLevel) bool
 
 // wrapFunc wraps noramal Func makes it compatible with FuncCtx

errors.go

@@ -101,7 +101,9 @@ type FieldError interface {
 	// returns the namespace for the field error, with the tag
 	// name taking precedence over the fields actual name.
 	//
-	// eq. JSON name "User.fname" see ActualNamespace for comparison
+	// eg. JSON name "User.fname"
+	//
+	// See StructNamespace() for a version that returns actual names.
 	//
 	// NOTE: this field can be blank when validating a single primitive field
 	// using validate.Field(...) as there is no way to extract it's name

struct_level.go

@@ -52,7 +52,7 @@ type StructLevel interface {
 	//
 	// tag can be an existing validation tag or just something you make up
 	// and process on the flip side it's up to you.
-	ReportError(field interface{}, fieldName, altName, tag, param string)
+	ReportError(field interface{}, fieldName, structFieldName string, tag, param string)
 
 	// reports an error just by passing ValidationErrors
 	//
@@ -63,9 +63,6 @@ type StructLevel interface {
 	// eg. pass 'User.FirstName' or 'Users[0].FirstName' depending
 	// on the nesting. most of the time they will be blank, unless you validate
 	// at a level lower the the current field depth
-	//
-	// tag can be an existing validation tag or just something you make up
-	// and process on the flip side it's up to you.
 	ReportValidationErrors(relativeNamespace, relativeActualNamespace string, errs ValidationErrors)
 }
 

validator_instance.go

@@ -176,12 +176,8 @@ func (v *Validate) RegisterAlias(alias, tags string) {
 }
 
 // RegisterStructValidation registers a StructLevelFunc against a number of types.
-// This is akin to implementing the 'Validatable' interface, but for structs for which
-// you may not have access or rights to change.
 //
-// NOTES:
+// NOTE:
-// - if this and the 'Validatable' interface are implemented the Struct Level takes precedence as to enable
-// a struct out of your control's validation to be overridden
 // - this method is not thread-safe it is intended that these all be registered prior to any validation
 func (v *Validate) RegisterStructValidation(fn StructLevelFunc, types ...interface{}) {
 	v.RegisterStructValidationCtx(wrapStructLevelFunc(fn), types...)
@@ -189,12 +185,8 @@ func (v *Validate) RegisterStructValidation(fn StructLevelFunc, types ...interfa
 
 // RegisterStructValidationCtx registers a StructLevelFuncCtx against a number of types and allows passing
 // of contextual validation information via context.Context.
-// This is akin to implementing a 'Validatable' interface, but for structs for which
-// you may not have access or rights to change.
 //
-// NOTES:
+// NOTE:
-// - if this and the 'Validatable' interface are implemented the Struct Level takes precedence as to enable
-// a struct out of your control's validation to be overridden
 // - this method is not thread-safe it is intended that these all be registered prior to any validation
 func (v *Validate) RegisterStructValidationCtx(fn StructLevelFuncCtx, types ...interface{}) {
 
@@ -494,9 +486,10 @@ func (v *Validate) StructExceptCtx(ctx context.Context, s interface{}, fields ..
 // var i int
 // validate.Var(i, "gt=1,lt=10")
 //
-// WARNING: a struct can be passed for validation eg. time.Time is a struct or if you have a custom type and have registered
+// WARNING: a struct can be passed for validation eg. time.Time is a struct or
-//          a custom type handler, so must allow it; however unforseen validations will occur if trying to validate a struct
+// if you have a custom type and have registered a custom type handler, so must
-//          that is meant to be passed to 'validate.Struct'
+// allow it; however unforseen validations will occur if trying to validate a
+// struct that is meant to be passed to 'validate.Struct'
 //
 // It returns InvalidValidationError for bad values passed in and nil or ValidationErrors as error otherwise.
 // You will need to assert the error if it's not nil eg. err.(validator.ValidationErrors) to access the array of errors.
@@ -511,9 +504,10 @@ func (v *Validate) Var(field interface{}, tag string) error {
 // var i int
 // validate.Var(i, "gt=1,lt=10")
 //
-// WARNING: a struct can be passed for validation eg. time.Time is a struct or if you have a custom type and have registered
+// WARNING: a struct can be passed for validation eg. time.Time is a struct or
-//          a custom type handler, so must allow it; however unforseen validations will occur if trying to validate a struct
+// if you have a custom type and have registered a custom type handler, so must
-//          that is meant to be passed to 'validate.Struct'
+// allow it; however unforseen validations will occur if trying to validate a
+// struct that is meant to be passed to 'validate.Struct'
 //
 // It returns InvalidValidationError for bad values passed in and nil or ValidationErrors as error otherwise.
 // You will need to assert the error if it's not nil eg. err.(validator.ValidationErrors) to access the array of errors.
@@ -562,9 +556,10 @@ func (v *Validate) VarCtx(ctx context.Context, field interface{}, tag string) (e
 // s2 := "abcd"
 // validate.VarWithValue(s1, s2, "eqcsfield") // returns true
 //
-// WARNING: a struct can be passed for validation eg. time.Time is a struct or if you have a custom type and have registered
+// WARNING: a struct can be passed for validation eg. time.Time is a struct or
-//          a custom type handler, so must allow it; however unforseen validations will occur if trying to validate a struct
+// if you have a custom type and have registered a custom type handler, so must
-//          that is meant to be passed to 'validate.Struct'
+// allow it; however unforseen validations will occur if trying to validate a
+// struct that is meant to be passed to 'validate.Struct'
 //
 // It returns InvalidValidationError for bad values passed in and nil or ValidationErrors as error otherwise.
 // You will need to assert the error if it's not nil eg. err.(validator.ValidationErrors) to access the array of errors.
@@ -580,9 +575,10 @@ func (v *Validate) VarWithValue(field interface{}, other interface{}, tag string
 // s2 := "abcd"
 // validate.VarWithValue(s1, s2, "eqcsfield") // returns true
 //
-// WARNING: a struct can be passed for validation eg. time.Time is a struct or if you have a custom type and have registered
+// WARNING: a struct can be passed for validation eg. time.Time is a struct or
-//          a custom type handler, so must allow it; however unforseen validations will occur if trying to validate a struct
+// if you have a custom type and have registered a custom type handler, so must
-//          that is meant to be passed to 'validate.Struct'
+// allow it; however unforseen validations will occur if trying to validate a
+// struct that is meant to be passed to 'validate.Struct'
 //
 // It returns InvalidValidationError for bad values passed in and nil or ValidationErrors as error otherwise.
 // You will need to assert the error if it's not nil eg. err.(validator.ValidationErrors) to access the array of errors.