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

docs/src/test/java/com/example/mockmvc/EveryTestPreprocessing.java

@@ -46,16 +46,16 @@ public class EveryTestPreprocessing {
 	// tag::setup[]
 	private MockMvc mockMvc;
 
-	private RestDocumentationResultHandler document;
+	private RestDocumentationResultHandler documentationHandler;
 
 	@Before
 	public void setup() {
-		this.document = document("{method-name}", // <1>
+		this.documentationHandler = document("{method-name}", // <1>
 				preprocessRequest(removeHeaders("Foo")),
 				preprocessResponse(prettyPrint()));
 		this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
 				.apply(documentationConfiguration(this.restDocumentation))
-				.alwaysDo(this.document) // <2>
+				.alwaysDo(this.documentationHandler) // <2>
 				.build();
 	}
 
@@ -63,10 +63,11 @@ public class EveryTestPreprocessing {
 
 	public void use() throws Exception {
 		// tag::use[]
-		this.document.snippets( // <1>
-				links(linkWithRel("self").description("Canonical self link")));
-		this.mockMvc.perform(get("/")) // <2>
-				.andExpect(status().isOk());
+		this.mockMvc.perform(get("/")) // <1>
+				.andExpect(status().isOk())
+				.andDo(this.documentationHandler.document( // <2>
+						links(linkWithRel("self").description("Canonical self link"))
+				));
 		// end::use[]
 	}