HV-1363 Improve the documentation

Author: gsmet

documentation/src/main/asciidoc/ch12.asciidoc

@@ -677,59 +677,66 @@ validator factory still is referenced by application code.
 ====
 
 [[section-getter-property-selection-strategy]]
-=== Getter property selection strategy configuration
+=== Customizing the getter property selection strategy
 
-When a regular validation operation is performed on an object it's properties get validated. Per
-JavaBean specification, a property can either be a field or a getter. Hibernate Validator uses
-next set of rules to determine if a method is a getter or not:
+When a bean is validated by Hibernate Validator, its properties get validated. A property can either
+be a field or a getter.
+By default, Hibernate Validator respects the JavaBeans specification and considers a method as a getter as soon
+as one of the conditions below is true:
 
-- a method name starts with `get`, it has a nonvoid return type and has no parameters
-- a method name starts with `is`, has a return type of `boolean` and has no parameters
-- a method name starts with `has`, has a return type of `boolean` and has no parameters (this
-is a Hibernate Validator specific rule and is not mandated by the JavaBeans specification)
+- the method name starts with `get`, it has a non-void return type and has no parameters;
+- the method name starts with `is`, has a return type of `boolean` and has no parameters;
+- the method name starts with `has`, has a return type of `boolean` and has no parameters (this rule
+is specific to Hibernate Validator and is not mandated by the JavaBeans specification)
 
-If any of the statements above are true - method is considered a getter.
+While these rules are usually appropriate when following the classic JavaBeans convention, it might happen,
+especially with code generators, that the JavaBeans naming convention is not followed and that the getters'
+names are following a different convention.
 
-When working with objects that do not follow JavaBean specification rules on getters. These rules
-should either be redefined or extended, in order to be able to fully validate the object. An example
-of such objects can be the ones constructed from classes that follow fluent design pattern (i.e. <<example-using-fluent-api-pattern>> ).
+In this case, the strategy for detecting getters should be redefined in order to fully validate the object.
+
+A classic example of this requirement is when the classes follow a fluent naming convention,
+as illustrated in <<example-using-fluent-api-pattern>>.
 
 [[example-using-fluent-api-pattern]]
-.A data class that uses nonstandard getters
+.A class that uses non-standard getters
 ====
 [source, JAVA, indent=0]
 ----
 include::{sourcedir}/org/hibernate/validator/referenceguide/chapter12/getterselectionstrategy/User.java[tags=include]
 ----
 ====
 
-If such object gets validated no validation will be performed on the methods:
+If such object gets validated, no validation will be performed on the getters as they are not detected
+by the standard strategy.
 
-.Validating a class with nonstandard getters and default getter property selection strategy
+.Validating a class with non-standard getters using the default getter property selection strategy
 ====
 [source, JAVA, indent=0]
 ----
 include::{sourcedir}/org/hibernate/validator/referenceguide/chapter12/getterselectionstrategy/GetterPropertySelectionStrategyTest.java[tags=no-strategy]
 ----
 ====
 
-To make Hibernate Validator treat such methods as getter properties a custom `GetterPropertySelectionStrategy`
-should be configured. In particular case the strategy can be implemeted like:
+To make Hibernate Validator treat such methods as properties, a custom `GetterPropertySelectionStrategy`
+should be configured.
+In this particular case, a possible implementation of the strategy would be:
 
-.Custom GetterPropertySelectionStrategy implementation
+.Custom `GetterPropertySelectionStrategy` implementation
 ====
 [source, JAVA, indent=0]
 ----
 include::{sourcedir}/org/hibernate/validator/referenceguide/chapter12/getterselectionstrategy/NoPrefixGetterPropertySelectionStrategy.java[tags=include]
 ----
 ====
 
-There are multiple ways to configuring Hibernate Validator to use such strategy. It can either be done
-programmatically (<<custom-getter-strategy-programmatically>>) or via the
-`hibernate.validator.getter_property_selection_strategy` property using XML configuration (<<custom-getter-strategy-xml>>).
+There are multiple ways to configure Hibernate Validator to use this strategy. It can either be done
+programmatically (see <<custom-getter-strategy-programmatically>>) or by using the
+`hibernate.validator.getter_property_selection_strategy` property in the XML configuration
+(see <<custom-getter-strategy-xml>>).
 
 [[custom-getter-strategy-programmatically]]
-.Configuring the custom `GetterPropertySelectionStrategy` programmatically
+.Configuring a custom `GetterPropertySelectionStrategy` programmatically
 ====
 [source, JAVA, indent=0]
 ----
@@ -738,7 +745,7 @@ include::{sourcedir}/org/hibernate/validator/referenceguide/chapter12/gettersele
 ====
 
 [[custom-getter-strategy-xml]]
-.Configuring the custom `GetterPropertySelectionStrategy` using XML property
+.Configuring a custom `GetterPropertySelectionStrategy` using an XML property
 ====
 [source, XML, indent=0]
 ----
@@ -748,8 +755,8 @@ include::{resourcesdir}/org/hibernate/validator/referenceguide/chapter12/getter-
 
 [WARNING]
 ====
-It is important to mention that in cases when any programmatic constraints are added using
-`HibernateValidatorConfiguration#addMapping(ConstraintMapping)` it should be done after the
-required getter property selection strategy is configured. Otherwise, the default one will be
-used.
+It is important to mention that in cases where programmatic constraints are added using
+`HibernateValidatorConfiguration#addMapping(ConstraintMapping)`, adding mappings should
+always be done after the required getter property selection strategy is configured.
+Otherwise, the default strategy will be used for the mappings added before defining the strategy.
 ====

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter12/getterselectionstrategy/GetterPropertySelectionStrategyTest.java

@@ -26,7 +26,7 @@ public void defaultStrategyUsed() {
 
 		Set<ConstraintViolation<User>> constraintViolations = validator.validate( user );
 
-		// as User has nonstandard getters no violations are triggered
+		// as User has non-standard getters no violations are triggered
 		assertEquals( 0, constraintViolations.size() );
 		//end::no-strategy[]
 	}
@@ -41,11 +41,11 @@ public void customNoPrefixStrategyUsed() {
 				.buildValidatorFactory()
 				.getValidator();
 
-		User user = new User( "first", "last", "not an email" );
+		User user = new User( "", "", "not an email" );
 
 		Set<ConstraintViolation<User>> constraintViolations = validator.validate( user );
 
-		assertEquals( 1, constraintViolations.size() );
+		assertEquals( 3, constraintViolations.size() );
 		//end::custom-strategy[]
 	}
 }

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter12/getterselectionstrategy/NoPrefixGetterPropertySelectionStrategy.java

@@ -13,8 +13,8 @@ public class NoPrefixGetterPropertySelectionStrategy implements GetterPropertySe
 
 	@Override
 	public boolean isGetter(ConstrainableExecutable executable) {
-		// We check that the method has non void return type and no parameters.
-		// And we do not care about method name at all.
+		// We check that the method has a non-void return type and no parameters.
+		// And we do not care about the method name.
 		return executable.getReturnType() != void.class
 				&& executable.getParameterTypes().length == 0;
 	}
@@ -26,7 +26,7 @@ public String getPropertyName(ConstrainableExecutable method) {
 
 	@Override
 	public Set<String> getGetterMethodNameCandidates(String propertyName) {
-		// As method name == property name there always is just one possible name for a method
+		// As method name == property name, there always is just one possible name for a method
 		return Collections.singleton( propertyName );
 	}
 }

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter12/getterselectionstrategy/User.java

@@ -8,9 +8,11 @@
 //tag::include[]
 public class User {
 
-	private final String firstName;
-	private final String lastName;
-	private final String email;
+	private String firstName;
+	private String lastName;
+	private String email;
+
+	// [...]
 
 	//end::include[]
 	public User(String firstName, String lastName, String email) {