I just stumbled upon some code example that still used {{SortField.STRING}}, which doesn't exist anymore, instead of the newer {{SortField.Type.STRING}}. I'm fixing it right now, but the real issue is that this kind of problem is hard to spot, and we can't be sure there aren't others in the documentation.
The thing is, code examples provided in the documentation are never compiled, thus when they become obsolete and do not compile, or do not run, anymore, we simply don't know.
The Hibernate Validator project uses a nice approach to solve this issue: they write code examples in JUnit tests, apply tags (with java comments) to the portions to be included in the documentation, and refer to these tags from the documentation.
That way, code example are assured to always compile, and even (if we define proper assertions) to always run as expected.
An example:
In the asciiDoc:
{code}
[[example-constraint-mapping]]
.Programmatic constraint declaration
====
[source, JAVA, indent=0]
----
include::{sourcedir}/org/hibernate/validator/referenceguide/chapter11/constraintapi/ConstraintApiTest.java[tags=constraintMapping]
----
====
{code}
And in the test (notice the comment with {{tag::}} and {{end::}}):
{code}
public class ConstraintApiTest {
@Test
public void constraintMapping() {
//tag::constraintMapping[]
HibernateValidatorConfiguration configuration = Validation
.byProvider( HibernateValidator.class )
.configure();
ConstraintMapping constraintMapping = configuration.createConstraintMapping();
constraintMapping
.type( Car.class )
.property( "manufacturer", FIELD )
.constraint( new NotNullDef() )
.property( "licensePlate", FIELD )
.ignoreAnnotations()
.constraint( new NotNullDef() )
.constraint( new SizeDef().min( 2 ).max( 14 ) )
.type( RentalCar.class )
.property( "rentalStation", METHOD )
.constraint( new NotNullDef() );
Validator validator = configuration.addMapping( constraintMapping )
.buildValidatorFactory()
.getValidator();
//end::constraintMapping[]
}
}
{code} |
|