Polish Snippet-related javadoc

Closes gh-136

spring-restdocs-core/src/main/java/org/springframework/restdocs/curl/CurlDocumentation.java

@@ -36,22 +36,22 @@ public abstract class CurlDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet containing the curl request for the
-	 * API call.
+	 * Returns a new {@code Snippet} that will document the curl request for the API
+	 * operation.
 	 *
-	 * @return the handler that will produce the snippet
+	 * @return the snippet that will document the curl request
 	 */
 	public static Snippet curlRequest() {
 		return new CurlRequestSnippet();
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet containing the curl request for the
-	 * API call. The given {@code attributes} will be available during snippet generation.
+	 * Returns a new {@code Snippet} that will document the curl request for the API
+	 * operation. The given {@code attributes} will be available during snippet
+	 * generation.
 	 *
-	 * @param attributes Attributes made available during rendering of the curl request
-	 * snippet
-	 * @return the handler that will produce the snippet
+	 * @param attributes the attributes
+	 * @return the snippet that will document the curl request
 	 */
 	public static Snippet curlRequest(Map<String, Object> attributes) {
 		return new CurlRequestSnippet(attributes);

spring-restdocs-core/src/main/java/org/springframework/restdocs/http/HttpDocumentation.java

@@ -33,41 +33,44 @@ public abstract class HttpDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet containing the HTTP request for the
-	 * API call.
+	 * Returns a new {@code Snippet} that will document the HTTP request for the API
+	 * operation.
 	 *
-	 * @return the handler that will produce the snippet
+	 * @return the snippet that will document the HTTP request
 	 */
 	public static Snippet httpRequest() {
 		return new HttpRequestSnippet();
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet containing the HTTP request for the
-	 * API call. The given {@code attributes} will be available during snippet generation.
+	 * Returns a new {@code Snippet} that will document the HTTP request for the API
+	 * operation. The given {@code attributes} will be available during snippet
+	 * generation.
 	 *
 	 * @param attributes the attributes
-	 * @return the handler that will produce the snippet
+	 * @return the snippet that will document the HTTP request
 	 */
 	public static Snippet httpRequest(Map<String, Object> attributes) {
 		return new HttpRequestSnippet(attributes);
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet containing the HTTP response for the
-	 * API call.
-	 * @return the handler that will produce the snippet
+	 * Returns a {@code Snippet} that will document the HTTP response for the API
+	 * operation.
+	 *
+	 * @return the snippet that will document the HTTP response
 	 */
 	public static Snippet httpResponse() {
 		return new HttpResponseSnippet();
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet containing the HTTP response for the
-	 * API call. The given {@code attributes} will be available during snippet generation.
+	 * Returns a {@code Snippet} that will document the HTTP response for the API
+	 * operation. The given {@code attributes} will be available during snippet
+	 * generation.
 	 *
 	 * @param attributes the attributes
-	 * @return the handler that will produce the snippet
+	 * @return the snippet that will document the HTTP response
 	 */
 	public static Snippet httpResponse(Map<String, Object> attributes) {
 		return new HttpResponseSnippet(attributes);

spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java

@@ -43,12 +43,17 @@ public abstract class HypermediaDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the links in the API
-	 * call's response. Links will be extracted from the response automatically based on
-	 * its content type.
+	 * Returns a new {@code Snippet} that will document the links in the API operation's
+	 * response. Links will be extracted from the response automatically based on its
+	 * content type and will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is present in the response, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
+	 * is documented, is not marked as optional, and is not present in the response, a
+	 * failure will also occur.
 	 *
-	 * @param descriptors The descriptions of the response's links
-	 * @return the handler
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
 	 */
 	public static Snippet links(LinkDescriptor... descriptors) {
 		return new LinksSnippet(new ContentTypeLinkExtractor(),
@@ -56,14 +61,19 @@ public abstract class HypermediaDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the links in the API
-	 * call's response. The given {@code attributes} will be available during snippet
-	 * generation. Links will be extracted from the response automatically based on its
-	 * content type.
+	 * Returns a new {@code Snippet} that will document the links in the API call's
+	 * response. The given {@code attributes} will be available during snippet generation.
+	 * Links will be extracted from the response automatically based on its content type
+	 * and will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is present in the response, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
+	 * is documented, is not marked as optional, and is not present in the response, a
+	 * failure will also occur.
 	 *
-	 * @param attributes Attributes made available during rendering of the links snippet
-	 * @param descriptors The descriptions of the response's links
-	 * @return the handler
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
 	 */
 	public static Snippet links(Map<String, Object> attributes,
 			LinkDescriptor... descriptors) {
@@ -72,13 +82,18 @@ public abstract class HypermediaDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the links in the API
-	 * call's response. Links will be extracted from the response using the given
-	 * {@code linkExtractor}.
+	 * Returns a new {@code Snippet} that will document the links in the API operation's
+	 * response. Links will be extracted from the response using the given
+	 * {@code linkExtractor} and will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is present in the response, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
+	 * is documented, is not marked as optional, and is not present in the response, a
+	 * failure will also occur.
 	 *
-	 * @param linkExtractor Used to extract the links from the response
-	 * @param descriptors The descriptions of the response's links
-	 * @return the handler
+	 * @param linkExtractor used to extract the links from the response
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
 	 */
 	public static Snippet links(LinkExtractor linkExtractor,
 			LinkDescriptor... descriptors) {
@@ -86,15 +101,20 @@ public abstract class HypermediaDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the links in the API
-	 * call's response. The given {@code attributes} will be available during snippet
-	 * generation. Links will be extracted from the response using the given
-	 * {@code linkExtractor}.
+	 * Returns a new {@code Snippet} that will document the links in the API operation's
+	 * response. The given {@code attributes} will be available during snippet generation.
+	 * Links will be extracted from the response using the given {@code linkExtractor} and
+	 * will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is present in the response, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
+	 * is documented, is not marked as optional, and is not present in the response, a
+	 * failure will also occur.
 	 *
-	 * @param attributes Attributes made available during rendering of the links snippet
-	 * @param linkExtractor Used to extract the links from the response
-	 * @param descriptors The descriptions of the response's links
-	 * @return the handler
+	 * @param attributes the attributes
+	 * @param linkExtractor used to extract the links from the response
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
 	 */
 	public static Snippet links(LinkExtractor linkExtractor,
 			Map<String, Object> attributes, LinkDescriptor... descriptors) {
@@ -104,9 +124,19 @@ public abstract class HypermediaDocumentation {
 	/**
 	 * Returns a {@code LinkExtractor} capable of extracting links in Hypermedia
 	 * Application Language (HAL) format where the links are found in a map named
-	 * {@code _links}.
+	 * {@code _links}. For example:
 	 *
-	 * @return The extract for HAL-style links
+	 * <pre>
+	 * {
+	 *     "_links": {
+	 *         "self": {
+	 *             "href": "http://example.com/foo"
+	 *         }
+	 *     }
+	 * }
+	 * </pre>
+	 *
+	 * @return The extractor for HAL-style links
 	 */
 	public static LinkExtractor halLinks() {
 		return new HalLinkExtractor();
@@ -114,7 +144,18 @@ public abstract class HypermediaDocumentation {
 
 	/**
 	 * Returns a {@code LinkExtractor} capable of extracting links in Atom format where
-	 * the links are found in an array named {@code links}.
+	 * the links are found in an array named {@code links}. For example:
+	 *
+	 * <pre>
+	 * {
+	 *     "links": [
+	 *         {
+	 *             "rel": "self",
+	 *             "href": "http://example.com/foo"
+	 *         }
+	 *     ]
+     * }
+	 * </pre>
 	 *
 	 * @return The extractor for Atom-style links
 	 */

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

@@ -99,18 +99,18 @@ public abstract class PayloadDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the fields of the API
-	 * call's request.
+	 * Returns a {@code Snippet} that will document the fields of the API operations's
+	 * request payload. The fields will be documented using the given {@code descriptors}.
 	 * <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
+	 * If a field is present in the request payload, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet 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 descriptions of the request's fields
-	 * @return the handler
+	 * @param descriptors the descriptions of the request payload's fields
+	 * @return the snippet that will document the fields
 	 * @see #fieldWithPath(String)
 	 */
 	public static Snippet requestFields(FieldDescriptor... descriptors) {
@@ -118,20 +118,20 @@ public abstract class PayloadDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the fields of the API
-	 * call's request. The given {@code attributes} will be available during snippet
-	 * generation.
+	 * Returns a {@code Snippet} that will document the fields of the API operation's
+	 * request payload. The fields will be documented using the given {@code descriptors}
+	 * and the given {@code attributes} will be available during snippet generation.
 	 * <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.
+	 * If a field is present in the request payload, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * field is documented, is not marked as optional, and is not present in the request
+	 * payload, 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 attributes Attributes made available during rendering of the snippet
-	 * @param descriptors The descriptions of the request's fields
-	 * @return the handler
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request payload's fields
+	 * @return the snippet that will document the fields
 	 * @see #fieldWithPath(String)
 	 */
 	public static Snippet requestFields(Map<String, Object> attributes,
@@ -140,18 +140,19 @@ public abstract class PayloadDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the fields of the API
-	 * call's response.
+	 * Returns a {@code Snippet} that will document the fields of the API operation's
+	 * response payload. The fields will be documented using the given {@code descriptors}
+	 * .
 	 * <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.
+	 * If a field is present in the response payload, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * field is documented, is not marked as optional, and is not present in the response
+	 * payload, 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 descriptions of the response's fields
-	 * @return the handler
+	 * @param descriptors the descriptions of the response payload's fields
+	 * @return the snippet that will document the fields
 	 * @see #fieldWithPath(String)
 	 */
 	public static Snippet responseFields(FieldDescriptor... descriptors) {
@@ -159,20 +160,20 @@ public abstract class PayloadDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the fields of the API
-	 * call's response. The given {@code attributes} will be available during snippet
-	 * generation.
+	 * Returns a {@code Snippet} that will document the fields of the API operation's
+	 * response payload. The fields will be documented using the given {@code descriptors}
+	 * and the given {@code attributes} will be available during snippet generation.
 	 * <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.
+	 * If a field is present in the response payload, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * field is documented, is not marked as optional, and is not present in the response
+	 * payload, 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 attributes Attributes made available during rendering of the snippet
-	 * @param descriptors The descriptions of the response's fields
-	 * @return the handler
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the response payload's fields
+	 * @return the snippet that will document the fields
 	 * @see #fieldWithPath(String)
 	 */
 	public static Snippet responseFields(Map<String, Object> attributes,

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java

@@ -19,11 +19,8 @@ package org.springframework.restdocs.request;
 import java.util.Arrays;
 import java.util.Map;
 
-import javax.servlet.ServletRequest;
-
+import org.springframework.restdocs.operation.OperationRequest;
 import org.springframework.restdocs.snippet.Snippet;
-import org.springframework.web.bind.annotation.PathVariable;
-import org.springframework.web.bind.annotation.RequestParam;
 
 /**
  * Static factory methods for documenting aspects of a request sent to a RESTful API.
@@ -48,26 +45,36 @@ public abstract class RequestDocumentation {
 	}
 
 	/**
-	 * Returns a snippet that will document the path parameters from the API call's
-	 * request.
+	 * Returns a {@code Snippet} that will document the path parameters from the API
+	 * operation's request. The parameters will be documented using the given
+	 * {@code descriptors}.
+	 * <p>
+	 * If a parameter is present in the request path, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * parameter is documented, is not marked as optional, and is not present in the
+	 * request path, a failure will also occur.
 	 *
-	 * @param descriptors The descriptions of the parameters in the request's path
-	 * @return the snippet
-	 * @see PathVariable
+	 * @param descriptors the descriptions of the parameters in the request's path
+	 * @return the snippet that will document the parameters
 	 */
 	public static Snippet pathParameters(ParameterDescriptor... descriptors) {
 		return new PathParametersSnippet(Arrays.asList(descriptors));
 	}
 
 	/**
-	 * Returns a snippet that will document the path parameters from the API call's
-	 * request. The given {@code attributes} will be available during snippet rendering.
+	 * Returns a {@code Snippet} that will document the path parameters from the API
+	 * operation's request. The given {@code attributes} will be available during snippet
+	 * rendering and the parameters will be documented using the given {@code descriptors}
+	 * .
+	 * <p>
+	 * If a parameter is present in the request path, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * parameter is documented, is not marked as optional, and is not present in the
+	 * request path, a failure will also occur.
 	 *
-	 * @param attributes Attributes made available during rendering of the path parameters
-	 * snippet
-	 * @param descriptors The descriptions of the parameters in the request's path
-	 * @return the snippet
-	 * @see PathVariable
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the parameters in the request's path
+	 * @return the snippet that will document the parameters
 	 */
 	public static Snippet pathParameters(Map<String, Object> attributes,
 			ParameterDescriptor... descriptors) {
@@ -75,28 +82,38 @@ public abstract class RequestDocumentation {
 	}
 
 	/**
-	 * Returns a snippet that will document the request parameters from the API call's
-	 * request.
+	 * Returns a {@code Snippet} that will document the parameters from the API
+	 * operation's request. The parameters will be documented using the given
+	 * {@code descriptors}.
+	 * <p>
+	 * If a parameter is present in the request, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * parameter is documented, is not marked as optional, and is not present in the
+	 * request, a failure will also occur.
 	 *
 	 * @param descriptors The descriptions of the request's parameters
 	 * @return the snippet
-	 * @see RequestParam
-	 * @see ServletRequest#getParameterMap()
+	 * @see OperationRequest#getParameters()
 	 */
 	public static Snippet requestParameters(ParameterDescriptor... descriptors) {
 		return new RequestParametersSnippet(Arrays.asList(descriptors));
 	}
 
 	/**
-	 * Returns a snippet that will document the request parameters from the API call's
-	 * request. The given {@code attributes} will be available during snippet rendering.
+	 * Returns a {@code Snippet} that will document the parameters from the API
+	 * operation's request. The given {@code attributes} will be available during snippet
+	 * rendering and the parameters will be documented using the given {@code descriptors}
+	 * .
+	 * <p>
+	 * If a parameter is present in the request, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * parameter is documented, is not marked as optional, and is not present in the
+	 * request, a failure will also occur.
 	 *
-	 * @param attributes Attributes made available during rendering of the request
-	 * parameters snippet
-	 * @param descriptors The descriptions of the request's parameters
-	 * @return the snippet
-	 * @see RequestParam
-	 * @see ServletRequest#getParameterMap()
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request's parameters
+	 * @return the snippet that will document the parameters
+	 * @see OperationRequest#getParameters()
 	 */
 	public static Snippet requestParameters(Map<String, Object> attributes,
 			ParameterDescriptor... descriptors) {