Adds ServiceRegistry documentation.

fixes spring-projectsgh-170
fixes spring-projectsgh-196

Author: spencergibb

docs/src/main/asciidoc/spring-cloud-commons.adoc

@@ -321,6 +321,33 @@ By default, implementations of `DiscoveryClient` will auto-register the local Sp
 
 Commons now provides a `ServiceRegistry` interface which provides methods like `register(Registration)` and `deregister(Registration)` which allow you to provide custom registered services. `Registration` is a marker interface.
 
+[source,java,indent=0]
+----
+@Configuration
+@EnableDiscoveryClient(autoRegister=false)
+public class MyConfiguration {
+    private ServiceRegistry registry;
+
+    public MyConfiguration(ServiceRegistry registry) {
+        this.registry = registry;
+    }
+
+    // called via some external process, such as an event or a custom actuator endpoint
+    public void register() {
+        Registration registration = constructRegistration();
+        this.registry.register(registration);
+    }
+}
+----
+
+Each `ServiceRegistry` implementation has its own `Registry` implementation.
+
+
+==== ServiceRegistry Auto-Registration
+
+By default, the `ServiceRegistry` implementation will auto-register the running service. To disable that behavior, there are two methods. You can set `@EnableDiscoveryClient(autoRegister=false)` to permanently disable auto-registration. You can also set `spring.cloud.service-registry.auto-registration.enabled=false` to disable the behavior via configuration.
+
+
 ==== Service Registry Actuator Endpoint
 
 A `/service-registry` actuator endpoint is provided by Commons. This endpoint relys on a `Registration` bean in the Spring Application Context. Calling `/service-registry/instance-status` via a GET will return the status of the `Registration`. A POST to the same endpoint with a `String` body will change the status of the current `Registration` to the new value. Please see the documentation of the `ServiceRegistry` implementation you are using for the allowed values for updating the status and the values retured for the status.

spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java

@@ -21,7 +21,7 @@
 import org.springframework.cloud.client.ServiceInstance;
 
 /**
- * DiscoveryClient represents operations commonly available to Discovery service such as
+ * DiscoveryClient represents read operations commonly available to Discovery service such as
  * Netflix Eureka or consul.io
  * @author Spencer Gibb
  */

spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/Registration.java

@@ -1,7 +1,10 @@
 package org.springframework.cloud.client.serviceregistry;
 
 /**
+ * A marker interface used by a {@link ServiceRegistry}.
+ *
  * @author Spencer Gibb
+ * @since 1.2.0
  */
 public interface Registration {
 

spring-cloud-commons/src/main/java/org/springframework/cloud/client/serviceregistry/ServiceRegistry.java

@@ -1,19 +1,48 @@
 package org.springframework.cloud.client.serviceregistry;
 
 /**
- * TODO: write javadoc
+ * Contract to register and deregister instances with a Service Registry.
+ *
  * @author Spencer Gibb
+ * @since 1.2.0
  */
 public interface ServiceRegistry<R extends Registration> {
+
+	/**
+	 * Register the registration. Registrations typically have information about
+	 * instances such as: hostname and port.
+	 * @param registration the registraion
+	 */
 	void register(R registration);
 
+	/**
+	 * Deregister the registration.
+	 * @param registration
+	 */
 	void deregister(R registration);
 
+	/**
+	 * Close the ServiceRegistry. This a lifecycle method.
+	 */
 	void close();
 
-	// TODO: return value for success?
+	/**
+	 * Sets the status of the registration. The status values are determined
+	 * by the individual implementations.
+	 *
+	 * @see org.springframework.cloud.client.serviceregistry.endpoint.ServiceRegistryEndpoint
+	 * @param registration the registration to update
+	 * @param status the status to set
+	 */
 	void setStatus(R registration, String status);
 
-	// TODO: concrete return value? Interface?
-	Object getStatus(R registration);
+	/**
+	 * Gets the status of a particular registration.
+	 *
+	 * @see org.springframework.cloud.client.serviceregistry.endpoint.ServiceRegistryEndpoint
+	 * @param registration the registration to query
+	 * @param <T> the type of the status
+	 * @return the status of the registration
+	 */
+	<T> T getStatus(R registration);
 }