From 770163b1e1f915b7227ba68dbce75412864842c9 Mon Sep 17 00:00:00 2001 From: Aaron Lehmann Date: Tue, 29 Aug 2017 18:44:39 -0700 Subject: [PATCH] Documentation fixes This fixes a few documentation issues I noticed. - Explain what Func is supposed to return. - Remove change reference to ActualNamespace to mention StructNamespace instead. - Remove references to Validatable, which no longer exists. - Fix godoc formatting. - Delete extra text from ReportValidationErrors comment. - Change ReportError interface definition so its arguments are named consistently with what they do. --- baked_in.go | 6 ++++-- errors.go | 4 +++- struct_level.go | 5 +---- validator_instance.go | 40 ++++++++++++++++++---------------------- 4 files changed, 26 insertions(+), 29 deletions(-) diff --git a/baked_in.go b/baked_in.go index 7ea3ec3..7828248 100644 --- a/baked_in.go +++ b/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 diff --git a/errors.go b/errors.go index 820b4bd..85f65ef 100644 --- a/errors.go +++ b/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 diff --git a/struct_level.go b/struct_level.go index e17bc5c..16c620d 100644 --- a/struct_level.go +++ b/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) } diff --git a/validator_instance.go b/validator_instance.go index da52481..e917835 100644 --- a/validator_instance.go +++ b/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: -// - 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 +// NOTE: // - 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: -// - 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 +// NOTE: // - 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 -// a custom type handler, so must allow it; however unforseen validations will occur if trying to validate a struct -// that is meant to be passed to 'validate.Struct' +// WARNING: a struct can be passed for validation eg. time.Time is a struct or +// if you have a custom type and have registered a custom type handler, so must +// 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 -// a custom type handler, so must allow it; however unforseen validations will occur if trying to validate a struct -// that is meant to be passed to 'validate.Struct' +// WARNING: a struct can be passed for validation eg. time.Time is a struct or +// if you have a custom type and have registered a custom type handler, so must +// 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 -// a custom type handler, so must allow it; however unforseen validations will occur if trying to validate a struct -// that is meant to be passed to 'validate.Struct' +// WARNING: a struct can be passed for validation eg. time.Time is a struct or +// if you have a custom type and have registered a custom type handler, so must +// 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 -// a custom type handler, so must allow it; however unforseen validations will occur if trying to validate a struct -// that is meant to be passed to 'validate.Struct' +// WARNING: a struct can be passed for validation eg. time.Time is a struct or +// if you have a custom type and have registered a custom type handler, so must +// 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.