address review feedback - round 1

Author: aaron-prindle

contributors/devel/sig-architecture/api-conventions.md

@@ -1953,7 +1953,9 @@ the future, an HTTP/2 implementation will be exposed that deprecates SPDY.
 
 ## Validation
 
-API objects are validated upon receipt by the apiserver. Validation can be implemented in two ways: declaratively, using tags on the Go type definitions, or manually, by writing validation functions. For all new APIs, declarative validation is the preferred approach for the validation rules it supports.  For more information see the [declarative validation documentation](api_changes.md).  Validation errors are
+API objects are validated upon receipt by the apiserver. 
+Validation can be implemented in two ways: declaratively, using tags on the Go type definitions, or manually, by writing validation functions. 
+For all new APIs, declarative validation is the preferred approach for the validation rules it supports.  For more information see the [declarative validation documentation](api_changes.md#declarative-validation).  Validation errors are
 flagged and returned to the caller in a `Failure` status with `reason` set to
 `Invalid`. In order to facilitate consistent error messages, we ask that
 validation logic adheres to the following guidelines whenever possible (though

contributors/devel/sig-architecture/api_changes.md

@@ -647,12 +647,16 @@ Of course, code needs tests - `pkg/apis/<group>/validation/validation_test.go`.
 
 ### Declarative Validation
 
-For new APIs, developers should use declarative validation for all validation rules that declarative validation supports. See the [declarative validation tag catalog](https://kubernetes.io/docs/reference/using-api/declarative-validation/) for the list of supported validation rules.  This allows you to define validation rules directly on the API types using special Go comment tags. Using this validation rules are easier to write, review, and maintain as they live alongside the type and field definitions.
+For new APIs, developers should use declarative validation for all validation rules that declarative validation supports. 
+See the [declarative validation tag catalog](https://kubernetes.io/docs/reference/using-api/declarative-validation/) for the list of supported validation rules.  
+This allows you to define validation rules directly on the API types using special Go comment tags. 
+These validation rules are easier to write, review, and maintain as they live alongside the type and field definitions.
 
 A new code generator, `validation-gen`, processes these tags to produce the validation logic automatically, reducing the need to write manual validation code in `validation.go`.
 
 
-To use declarative validation below are broadly steps to setup the validation code generation. For APIs already using declarative validation, the first 2 plumbing steps can be skipped:
+Setting up validation code generation involves the following steps. 
+For APIs already using declarative validation, the first 2 plumbing steps can be skipped:
 - Register the desired API group with validation-gen, similar to other code generators([Example PR doc.go change](https://github.com/kubernetes/kubernetes/pull/130724))
 - Wire up the `strategy.go` for the desired API group to use declarative validation ([Example PR strategy.go change](https://github.com/kubernetes/kubernetes/pull/130724))
 - Add declarative validation tags to the types and fields of the registered package ([Example PR types.go change](https://github.com/kubernetes/kubernetes/pull/130725))
@@ -691,7 +695,14 @@ type ReplicationControllerSpec struct {
 
 In this example, the `+k8s:optional` and `+k8s:minimum=0` tags specify that the `Replicas` and `MinReadySeconds` fields are optional and must have a value of at least 0 if present.
 
-After adding these tags to your types, you will need to run the code generator to create or update the validation functions. This is typically done by running `make update` or `hack/update-codegen.sh`.  To only run the declarative validation code generator, use `hack/update-codegen.sh validation`.  Running the validation-gen code generator will create a `zz_generated.validations.go` file for the declarative validations of the associated tagged API types and fields.  The generated validation methods in this file are then called via the modified `strategy.go` file in the above steps.
+After adding these tags to your types, you will need to run the code generator to create or update the validation functions. 
+This is typically done by running `make update` or `hack/update-codegen.sh`.  
+To only run the declarative validation code generator, use `hack/update-codegen.sh validation`.  
+Running the validation-gen code generator will create a `zz_generated.validations.go` file for the declarative validations of the associated tagged API types and fields.  
+The generated validation methods in this file are then called via the modified `strategy.go` file in the above steps.
+
+Testing the validation logic for the behaviour of a type is identical to the testing that would be done for hand-written validation code.  
+Users will need to write go unit tests similar to what is done for hand-written validation logic that verify specific cases are allowed, disallowed, etc and the validation behaviour is as expected.
 
 While the goal is to express as much validation declaratively as possible, some complex or validation rules might still require manual implementation in `validation.go`.