#891 - Overhauled reference documentation on EntityLinks.

Added new paragraphs on EntityLinks, ControllerEntityLinks, TypedEntityLinks and using EntityLinks as SPI.

Polished Javadoc of ControllerEntityLinks and its unit tests.

src/main/java/org/springframework/hateoas/server/core/ControllerEntityLinks.java

@@ -25,30 +25,32 @@ import org.springframework.hateoas.server.ExposesResourceFor;
 import org.springframework.hateoas.server.LinkBuilder;
 import org.springframework.hateoas.server.LinkBuilderFactory;
 import org.springframework.util.Assert;
+import org.springframework.web.bind.annotation.RequestMapping;
 
 /**
  * {@link EntityLinks} implementation which assumes a certain URI mapping structure:
  * <ol>
- * <li>A class-level mapping annotation that can contain template variables. The URI needs to expose the collection
- * resource, which means the controller has to expose a handler method mapped to an empty path: e.g.
- * {@code @RequestMapping(method = RequestMethod.GET)} in case of a Spring MVC controller.</li>
- * <li>Individual resources are exposed via a nested mapping consisting of the id of the managed entity, e.g. {@code
- * @RequestMapping("/{id}")}.<li>
+ * <li>A class-level {@link ExposesResourceFor} annotation to declare that the annotated controller exposes collection
+ * and item resources for.</li>
+ * <li>An {@link RequestMapping} annotation to form the base URI of the collection resource.</li>
+ * <li>A controller method with a mapping annotation to actually handle at least one HTTP method.</li>
+ * <li>A controller method that maps a subordinate resource taking a path variable to identify an item resource.</li>
  * </ol>
+ *
  * <pre>
- * @Controller
- * @ExposesResourceFor(Order.class)
- * @RequestMapping("/orders")
+ * &#64;Controller
+ * &#64;ExposesResourceFor(Order.class)
+ * &#64;RequestMapping("/orders")
  * class OrderController {
- * 
- *   @RequestMapping
+ *
+ *   &#64;GetMapping
  *   ResponseEntity orders(…) { … }
- *   
- *   @RequestMapping("/{id}")
- *   ResponseEntity order(@PathVariable("id") … ) { … }  
+ *
+ *   &#64;GetMapping("/{id}")
+ *   ResponseEntity order(@PathVariable("id") … ) { … }
  * }
  * </pre>
- * 
+ *
  * @author Oliver Gierke
  */
 public class ControllerEntityLinks extends AbstractEntityLinks {
@@ -58,9 +60,9 @@ public class ControllerEntityLinks extends AbstractEntityLinks {
 
 	/**
 	 * Creates a new {@link ControllerEntityLinks} inspecting the configured classes for the given annotation.
-	 * 
-	 * @param controllerTypes the controller classes to be inspected.
-	 * @param linkBuilderFactory the {@link LinkBuilder} to use to create links.
+	 *
+	 * @param controllerTypes the controller classes to be inspected, must not be {@literal null}.
+	 * @param linkBuilderFactory the {@link LinkBuilder} to use to create links, must not be {@literal null}.
 	 */
 	public ControllerEntityLinks(Iterable<? extends Class<?>> controllerTypes,
 			LinkBuilderFactory<? extends LinkBuilder> linkBuilderFactory) {
@@ -82,12 +84,12 @@ public class ControllerEntityLinks extends AbstractEntityLinks {
 		if (annotation != null) {
 			entityToController.put(annotation.value(), controllerType);
 		} else {
-			throw new IllegalArgumentException(String.format("Controller %s must be annotated with @ExposesResourceFor!",
-					controllerType.getName()));
+			throw new IllegalArgumentException(
+					String.format("Controller %s must be annotated with @ExposesResourceFor!", controllerType.getName()));
 		}
 	}
 
-	/* 
+	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.hateoas.EntityLinks#linkTo(java.lang.Class)
 	 */
@@ -96,7 +98,7 @@ public class ControllerEntityLinks extends AbstractEntityLinks {
 		return linkFor(entity, new Object[0]);
 	}
 
-	/* 
+	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.hateoas.EntityLinks#linkTo(java.lang.Class, java.lang.Object)
 	 */
@@ -116,7 +118,7 @@ public class ControllerEntityLinks extends AbstractEntityLinks {
 		return linkBuilderFactory.linkTo(controllerType, parameters);
 	}
 
-	/* 
+	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.hateoas.EntityLinks#getLinkToCollectionResource(java.lang.Class)
 	 */
@@ -125,7 +127,7 @@ public class ControllerEntityLinks extends AbstractEntityLinks {
 		return linkFor(entity).withSelfRel();
 	}
 
-	/* 
+	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.hateoas.EntityLinks#getLinkToSingleResource(java.lang.Class, java.lang.Object)
 	 */
@@ -134,7 +136,7 @@ public class ControllerEntityLinks extends AbstractEntityLinks {
 		return linkFor(entity).slash(id).withSelfRel();
 	}
 
-	/* 
+	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.plugin.core.Plugin#supports(java.lang.Object)
 	 */