Make descriptions more flexible

Previously, the description of a link, parameter, or field had to be a
String. Given the use of Mustache templates, this was unnecessarily
restrictive. It prevented the use of a richer object, the components of
which could then be accessed in a template.

This commit changes the description of links, parameters, and fields to
be an Object, thereby allowing richer objects to be used. The default
template will call toString on the description during rendering. Custom
templates can be used to make more sophisticated use of the description.

To ensure that the description is consistent across all descriptor
types, it has been moved up onto the AbstractDescriptor superclass.

Closes gh-123

spring-restdocs-core/src/test/java/org/springframework/restdocs/payload/RequestFieldsSnippetTests.java

@@ -179,6 +179,26 @@ public class RequestFieldsSnippetTests {
 						.request("http://localhost").content("{\"a\": \"foo\"}").build());
 	}
 
+	@Test
+	public void requestFieldsWithListDescription() throws IOException {
+		this.snippet.expectRequestFields("request-fields-with-list-description")
+				.withContents(
+						tableWithHeader("Path", "Type", "Description")
+								//
+								.row("a", "String", String.format(" - one%n - two"))
+								.configuration("[cols=\"1,1,1a\"]"));
+		TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);
+		when(resolver.resolveTemplateResource("request-fields")).thenReturn(
+				snippetResource("request-fields-with-list-description"));
+		new RequestFieldsSnippet(Arrays.asList(fieldWithPath("a").description(
+				Arrays.asList("one", "two"))))
+				.document(new OperationBuilder("request-fields-with-list-description",
+						this.snippet.getOutputDirectory())
+						.attribute(TemplateEngine.class.getName(),
+								new MustacheTemplateEngine(resolver))
+						.request("http://localhost").content("{\"a\": \"foo\"}").build());
+	}
+
 	@Test
 	public void xmlRequestFields() throws IOException {
 		this.snippet.expectRequestFields("xml-request").withContents( //

spring-restdocs-core/src/test/java/org/springframework/restdocs/test/SnippetMatchers.java

@@ -191,6 +191,11 @@ public class SnippetMatchers {
 			this.addLine(-1, "");
 			return this;
 		}
+
+		public AsciidoctorTableMatcher configuration(String configuration) {
+			this.addLine(0, configuration);
+			return this;
+		}
 	}
 
 	public static class SnippetMatcher extends BaseMatcher<File> {

spring-restdocs-core/src/test/resources/custom-snippet-templates/request-fields-with-list-description.snippet

@@ -0,0 +1,12 @@
+[cols="1,1,1a"]
+|===
+|Path|Type|Description
+
+{{#fields}}
+|{{path}}
+|{{type}}
+|{{#description}} - {{.}}
+{{/description}}
+
+{{/fields}}
+|===