Improve description of when fields are considered to be documented

Closes gh-82

docs/src/docs/asciidoc/documenting-your-api.adoc

@@ -77,11 +77,8 @@ snippet is named `request-fields.adoc`. For responses this snippet is named
 When documenting fields, the test will fail if an undocumented field is found in the
 payload. Similarly, the test will also fail if a documented field is not found in the
 payload and the field has not be marked as optional. For payloads with a hierarchical
-structure, when a point in the hierarchy is documented any fields beneath that point are
-also deemed to have been documented. This means that you do not have to document the
-entire hierarchy, but you may do so if you wish.
-
-
+structure, documenting a field is sufficient for all of its descendants to also be
+treated as having been documented.
 
 [[documenting-your-api-request-response-payloads-field-paths]]
 ==== Field paths

spring-restdocs/src/main/java/org/springframework/restdocs/RestDocumentationResultHandler.java

@@ -101,10 +101,12 @@ public class RestDocumentationResultHandler implements ResultHandler {
 	/**
 	 * Document the fields in the request using the given {@code descriptors}.
 	 * <p>
-	 * If a field is present in the request but is not described by one of the descriptors
-	 * a failure will occur when this handler is invoked. Similarly, if a field is
-	 * described but is not present in the request a failure will also occur when this
-	 * handler is invoked.
+	 * If a field is present in the request but is not documented by one of the
+	 * descriptors a failure will occur when this handler is invoked. Similarly, if a
+	 * field is documented, is not marked as optional, and is not present in the request a
+	 * failure will also occur. For payloads with a hierarchical structure, documenting a
+	 * field is sufficient for all of its descendants to also be treated as having been
+	 * documented.
 	 * 
 	 * @param descriptors the link descriptors
 	 * @return {@code this}
@@ -119,10 +121,12 @@ public class RestDocumentationResultHandler implements ResultHandler {
 	/**
 	 * Document the fields in the response using the given {@code descriptors}.
 	 * <p>
-	 * If a field is present in the response but is not described by one of the
+	 * If a field is present in the response but is not documented by one of the
 	 * descriptors a failure will occur when this handler is invoked. Similarly, if a
-	 * field is described but is not present in the response a failure will also occur
-	 * when this handler is invoked.
+	 * field is documented, is not marked as optional, and is not present in the response
+	 * a failure will also occur. For payloads with a hierarchical structure, documenting
+	 * a field is sufficient for all of its descendants to also be treated as having been
+	 * documented.
 	 * 
 	 * @param descriptors the link descriptors
 	 * @return {@code this}

spring-restdocs/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java

@@ -98,11 +98,19 @@ public abstract class PayloadDocumentation {
 	/**
 	 * Creates a {@code RequestFieldsSnippetResultHandler} that will produce a
 	 * documentation snippet for a request's fields.
+	 * <p>
+	 * If a field is present in the request but is not documented by one of the
+	 * descriptors a failure will occur when the handler is invoked. Similarly, if a field
+	 * is documented, is not marked as optional, and is not present in the request a
+	 * failure will also occur. For payloads with a hierarchical structure, documenting a
+	 * field is sufficient for all of its descendants to also be treated as having been
+	 * documented.
 	 * 
 	 * @param outputDir The directory to which the snippet should be written
 	 * @param descriptors The descriptions of the request's fields
 	 * @return the handler
 	 * @see RestDocumentationResultHandler#withRequestFields(FieldDescriptor...)
+	 * @see #fieldWithPath(String)
 	 */
 	public static FieldSnippetResultHandler documentRequestFields(String outputDir,
 			FieldDescriptor... descriptors) {
@@ -112,6 +120,13 @@ public abstract class PayloadDocumentation {
 	/**
 	 * Creates a {@code ResponseFieldsSnippetResultHandler} that will produce a
 	 * documentation snippet for a response's fields.
+	 * <p>
+	 * If a field is present in the response but is not documented by one of the
+	 * descriptors a failure will occur when the handler is invoked. Similarly, if a field
+	 * is documented, is not marked as optional, and is not present in the response a
+	 * failure will also occur. For payloads with a hierarchical structure, documenting a
+	 * field is sufficient for all of its descendants to also be treated as having been
+	 * documented.
 	 * 
 	 * @param outputDir The directory to which the snippet should be written
 	 * @param descriptors The descriptions of the response's fields