From 5a010160a15d2907647358d76b34b46a62a88c78 Mon Sep 17 00:00:00 2001
From: Andy Wilkinson <awilkinson@pivotal.io>
Date: Mon, 28 Sep 2015 20:11:11 +0100
Subject: [PATCH] Polish Snippet-related javadoc

Closes gh-136
---
 .../restdocs/curl/CurlDocumentation.java      | 16 +--
 .../restdocs/http/HttpDocumentation.java      | 27 ++---
 .../hypermedia/HypermediaDocumentation.java   | 99 +++++++++++++------
 .../payload/PayloadDocumentation.java         | 81 +++++++--------
 .../request/RequestDocumentation.java         | 73 ++++++++------
 .../mockmvc/MockMvcRestDocumentation.java     | 24 ++---
 .../RestDocumentationMockMvcConfigurer.java   | 18 ++++
 7 files changed, 209 insertions(+), 129 deletions(-)

diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/curl/CurlDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/curl/CurlDocumentation.java
index be692cc9..a3549443 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/curl/CurlDocumentation.java
+++ b/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);
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/http/HttpDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/http/HttpDocumentation.java
index 9aae38b7..f1bc8b38 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/http/HttpDocumentation.java
+++ b/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);
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java
index b167225e..c073484e 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java
+++ b/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
 	 */
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java
index 653442ed..56f8266f 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java
+++ b/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,
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java
index 345ec58c..61c33d5f 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java
+++ b/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) {
diff --git a/spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentation.java b/spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentation.java
index a41ed1cf..bedd3753 100644
--- a/spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentation.java
+++ b/spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentation.java
@@ -51,10 +51,10 @@ public abstract class MockMvcRestDocumentation {
 
 	/**
 	 * Documents the API call with the given {@code identifier} using the given
-	 * {@code snippets}.
+	 * {@code snippets} in addition to any default snippets.
 	 *
 	 * @param identifier an identifier for the API call that is being documented
-	 * @param snippets the snippets that will document the API call
+	 * @param snippets the snippets
 	 * @return a Mock MVC {@code ResultHandler} that will produce the documentation
 	 * @see MockMvc#perform(org.springframework.test.web.servlet.RequestBuilder)
 	 * @see ResultActions#andDo(org.springframework.test.web.servlet.ResultHandler)
@@ -66,12 +66,12 @@ public abstract class MockMvcRestDocumentation {
 
 	/**
 	 * Documents the API call with the given {@code identifier} using the given
-	 * {@code snippets}. The given {@code requestPreprocessor} is applied to the request
-	 * before it is documented.
+	 * {@code snippets} in addition to any default snippets. The given
+	 * {@code requestPreprocessor} is applied to the request before it is documented.
 	 *
 	 * @param identifier an identifier for the API call that is being documented
 	 * @param requestPreprocessor the request preprocessor
-	 * @param snippets the snippets that will document the API call
+	 * @param snippets the snippets
 	 * @return a Mock MVC {@code ResultHandler} that will produce the documentation
 	 * @see MockMvc#perform(org.springframework.test.web.servlet.RequestBuilder)
 	 * @see ResultActions#andDo(org.springframework.test.web.servlet.ResultHandler)
@@ -84,12 +84,12 @@ public abstract class MockMvcRestDocumentation {
 
 	/**
 	 * Documents the API call with the given {@code identifier} using the given
-	 * {@code snippets}. The given {@code responsePreprocessor} is applied to the request
-	 * before it is documented.
+	 * {@code snippets} in addition to any default snippets. The given
+	 * {@code responsePreprocessor} is applied to the request before it is documented.
 	 *
 	 * @param identifier an identifier for the API call that is being documented
 	 * @param responsePreprocessor the response preprocessor
-	 * @param snippets the snippets that will document the API call
+	 * @param snippets the snippets
 	 * @return a Mock MVC {@code ResultHandler} that will produce the documentation
 	 * @see MockMvc#perform(org.springframework.test.web.servlet.RequestBuilder)
 	 * @see ResultActions#andDo(org.springframework.test.web.servlet.ResultHandler)
@@ -102,14 +102,14 @@ public abstract class MockMvcRestDocumentation {
 
 	/**
 	 * Documents the API call with the given {@code identifier} using the given
-	 * {@code snippets}. The given {@code requestPreprocessor} and
-	 * {@code responsePreprocessor} are applied to the request and response respectively
-	 * before they are documented.
+	 * {@code snippets} in addition to any default snippets. The given
+	 * {@code requestPreprocessor} and {@code responsePreprocessor} are applied to the
+	 * request and response respectively before they are documented.
 	 *
 	 * @param identifier an identifier for the API call that is being documented
 	 * @param requestPreprocessor the request preprocessor
 	 * @param responsePreprocessor the response preprocessor
-	 * @param snippets the snippets that will document the API call
+	 * @param snippets the snippets
 	 * @return a Mock MVC {@code ResultHandler} that will produce the documentation
 	 * @see MockMvc#perform(org.springframework.test.web.servlet.RequestBuilder)
 	 * @see ResultActions#andDo(org.springframework.test.web.servlet.ResultHandler)
diff --git a/spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/RestDocumentationMockMvcConfigurer.java b/spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/RestDocumentationMockMvcConfigurer.java
index 536f831d..20f06771 100644
--- a/spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/RestDocumentationMockMvcConfigurer.java
+++ b/spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/RestDocumentationMockMvcConfigurer.java
@@ -19,6 +19,8 @@ package org.springframework.restdocs.mockmvc;
 import org.springframework.mock.web.MockHttpServletRequest;
 import org.springframework.restdocs.RestDocumentation;
 import org.springframework.restdocs.RestDocumentationContext;
+import org.springframework.restdocs.curl.CurlDocumentation;
+import org.springframework.restdocs.http.HttpDocumentation;
 import org.springframework.restdocs.snippet.RestDocumentationContextPlaceholderResolver;
 import org.springframework.restdocs.snippet.StandardWriterResolver;
 import org.springframework.restdocs.snippet.WriterResolver;
@@ -33,6 +35,22 @@ import org.springframework.web.context.WebApplicationContext;
 
 /**
  * A {@link MockMvcConfigurer} that can be used to configure the documentation.
+ * <p>
+ * In the absence of any {@link #snippets() customization} the following snippets will be
+ * produced by default:
+ * <ul>
+ * <li>{@link CurlDocumentation#curlRequest() Curl request}</li>
+ * <li>{@link HttpDocumentation#httpRequest() HTTP request}</li>
+ * <li>{@link HttpDocumentation#httpResponse() HTTP response}</li>
+ * </ul>
+ * <p>
+ * In the absence of any {@link #uris() customization}, documented URIs have the following
+ * defaults:
+ * <ul>
+ * <li>Scheme: {@code http}</li>
+ * <li>Host: {@code localhost}</li>
+ * <li>Port: {@code 8080}</li>
+ * </ul>
  *
  * @author Andy Wilkinson
  * @author Dmitriy Mayboroda