Improve the API for generating additional snippets

Previously, if alwaysDo was used and the user wanted to generate
one or more additional snippets when calling perform a separate call
to `snippets` was made prior to calling `perform`. This had two
problems:

 - it required the result handler to be stateful (see gh-243)
 - it wasn't clear that the additional snippets would be produced when
   a subsequent call to perform was made

This commit introduces a new API that allows the additional snippets
to be specified within the MockMvc call. The old API has been
deprecated and will be removed in 2.0.

Closes gh-249

spring-restdocs-mockmvc/src/test/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentationIntegrationTests.java

@@ -56,6 +56,8 @@ import static org.hamcrest.CoreMatchers.is;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.assertTrue;
 import static org.springframework.restdocs.cli.CliDocumentation.curlRequest;
+import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
+import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
 import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
 import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
 import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
@@ -329,6 +331,24 @@ public class MockMvcRestDocumentationIntegrationTests {
 				"http-response.adoc", "curl-request.adoc");
 	}
 
+	@Test
+	public void alwaysDoWithAdditionalSnippets() throws Exception {
+		RestDocumentationResultHandler documentation = document("{method-name}-{step}");
+		MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
+				.apply(documentationConfiguration(this.restDocumentation))
+				.alwaysDo(documentation).build();
+
+		mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
+				.andExpect(status().isOk()).andDo(documentation.document(
+						responseHeaders(headerWithName("a").description("one"))));
+
+		assertExpectedSnippetFilesExist(
+				new File(
+						"build/generated-snippets/always-do-with-additional-snippets-1/"),
+				"http-request.adoc", "http-response.adoc", "curl-request.adoc",
+				"response-headers.adoc");
+	}
+
 	@Test
 	public void preprocessedRequest() throws Exception {
 		MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.context)