Merge branch 'api-docs'

build.gradle

@@ -34,6 +34,15 @@ ext {
 
     junitVersion = "4.11"
     mockitoVersion = "1.9.5"
+    
+	javadocLinks = [
+		'http://docs.oracle.com/javase/7/docs/api/',
+		'http://docs.oracle.com/javaee/6/api/',
+		'http://docs.spring.io/spring/docs/current/javadoc-api/',
+		'http://docs.spring.io/spring-amqp/docs/latest-ga/api/',
+		'http://docs.spring.io/spring-data/data-mongo/docs/current/api/',
+		'http://docs.spring.io/spring-data/data-redis/docs/current/api/'
+	] as String[]    
 }
 
 subprojects {
@@ -51,13 +60,25 @@ subprojects {
     sourceCompatibility = 1.6
     targetCompatibility = 1.6
 
+	javadoc {
+        options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PROTECTED
+        options.author = true
+        options.header = project.name
+    }
+    
     task packageSources(type: Jar) {
         classifier = 'sources'
         from sourceSets.main.allSource
     }
+    
+	task javadocJar(type: Jar) {
+        classifier = "javadoc"
+        from javadoc
+    }    
 
     artifacts {
     		archives packageSources
+    		archives javadocJar
     }
 
     dependencies {
@@ -102,7 +123,40 @@ configure(rootProject) {
 		}
 	}
 	
+	task api(type: Javadoc) {
+        group = "Documentation"
+        description = "Generates aggregated Javadoc API documentation."
+        title = "${rootProject.description} ${version} API"
+        options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PROTECTED
+        options.author = true
+        options.header = rootProject.description
+        options.links(project.ext.javadocLinks)
+
+        source subprojects.collect { project ->
+            project.sourceSets.main.allJava
+        }
+
+        classpath = files(subprojects.collect { project ->
+            project.sourceSets.main.compileClasspath
+        })
+
+        maxMemory = "1024m"
+        destinationDir = new File(buildDir, "api")
+    }	
+	
+	task docsZip(type: Zip) {
+		group = 'Distribution'
+		classifier = 'docs'
+		description = "Builds -${classifier} archive containing api and reference " +
+			"for deployment at docs.spring.io/spring-cloud/docs."
+
+		from (api) {
+			into 'api'
+		}
+	}
+	
 	artifacts {
+		archives docsZip	
 		archives schemaZip
 	}
 }

cloudfoundry-connector/src/main/java/org/springframework/cloud/cloudfoundry/CloudFoundryConnector.java

@@ -60,7 +60,7 @@ public class CloudFoundryConnector extends AbstractCloudConnector<Map<String,Obj
 	 * <p>
 	 * Returns a list whose element is a map with service attributes. 
 	 * </p>
-	 * @return
+	 * @return parsed service data
 	 */
 	@SuppressWarnings("unchecked")
 	protected List<Map<String,Object>> getServicesData() {

core/src/main/java/org/springframework/cloud/Cloud.java

@@ -60,7 +60,7 @@ public class Cloud {
 	/**
 	 * @see CloudConnector#getApplicationInstanceInfo()
 	 * 
-	 * @return
+	 * @return information about the application instance
 	 */
 	public ApplicationInstanceInfo getApplicationInstanceInfo() {
 		return cloudConnector.getApplicationInstanceInfo();
@@ -83,7 +83,7 @@ public class Cloud {
 	
 	/**
 	 * @see CloudConnector#getServiceInfos()
-	 * @return
+	 * @return information about all services bound to the application
 	 */
 	public List<ServiceInfo> getServiceInfos() {
 		return cloudConnector.getServiceInfos();
@@ -98,8 +98,8 @@ public class Cloud {
 	 * <p> 
 	 * 
 	 * @param serviceConnectorType service connector type. 
-	 *                             Passing null returns all {@link ServiceInfo}s (matching that of {@link Cloud#getServiceInfo()} 
-	 * @return
+	 *                             Passing null returns all {@link ServiceInfo}s (matching that of {@link Cloud#getServiceInfos()} 
+	 * @return information about services bound to the application that could be transformed into the given connector type
 	 */
 	public <T> List<ServiceInfo> getServiceInfos(Class<T> serviceConnectorType) {
 		List<ServiceInfo> allServiceInfos = getServiceInfos();

core/src/main/java/org/springframework/cloud/app/ApplicationInstanceInfo.java

@@ -34,7 +34,7 @@ public interface ApplicationInstanceInfo {
 	 * <p>
 	 * Typical properties could include hostname and port etc.
 	 * 
-	 * @return
+	 * @return map of properties
 	 */
 	public Map<String, Object> getProperties();
 }

core/src/main/java/org/springframework/cloud/service/ServiceConnectorCreator.java

@@ -13,8 +13,8 @@ public interface ServiceConnectorCreator<SC, SI extends ServiceInfo> {
 	 * configuration
 	 * 
 	 * @param serviceInfo
-	 * @param serviceConnectorConfiguration
-	 * @return
+	 * @param serviceConnectorConfig
+	 * @return service connector
 	 */
 	SC create(SI serviceInfo, ServiceConnectorConfig serviceConnectorConfig);
 	

core/src/main/java/org/springframework/cloud/service/UriBasedServiceInfo.java

@@ -71,8 +71,8 @@ public abstract class UriBasedServiceInfo extends BaseServiceInfo {
 	/**
 	 * Validate the URI and clean it up by using defaults for any missing information, if possible.
 	 * 
-	 * @param uriInfo
-	 * @return
+	 * @param uriInfo uri info based on parsed payload
+	 * @return cleaned up uri info
 	 */
 	protected UriInfo validateAndCleanUriInfo(UriInfo uriInfo) {
 		return uriInfo;

heroku-connector/src/main/java/org/springframework/cloud/heroku/HerokuConnector.java

@@ -18,7 +18,8 @@ import org.springframework.cloud.util.EnvironmentAccessor;
 /**
  * Implementation of CloudConnector for Heroku
  * 
- * Currently support only the Postgres service.
+ * Currently support Postgres (default provided), Mysql (Cleardb), MongoDb (MongoLab, MongoHQ, MongoSoup),
+ * Redis (RedisToGo, RedisCloud, OpenRedis, RedisGreen), and AMQP (CloudAmqp).
  * 
  * @author Ramnivas Laddad
  *
@@ -74,7 +75,7 @@ public class HerokuConnector extends AbstractCloudConnector<HerokuConnector.KeyV
 	 * <p>
 	 * Returns map whose key is the env key and value is the associated url
 	 * </p>
-	 * @return
+	 * @return information about services bound to the app 
 	 */
 	protected List<KeyValuePair> getServicesData() {
 		List<KeyValuePair> serviceData = new ArrayList<KeyValuePair>();

spring-service-connector/src/main/java/org/springframework/cloud/config/java/AbstractCloudConfig.java

@@ -47,12 +47,8 @@ public abstract class AbstractCloudConfig implements BeanFactoryAware {
 	 * Get the cloud factory.
 	 * 
 	 * Most applications will never need this method, but provided here to cover corner cases.
-	 * 
-	 * Implementation note: This roundabout way of implementation is required to ensure that
-	 * a CloudFoundry bean if created in some other configuration is available, we should use
-	 * that.
 	 *  
-	 * @return
+	 * @return cloud factory
 	 */
 	protected CloudFactory cloudFactory() {
 		return cloudFactory;
@@ -75,12 +71,16 @@ public abstract class AbstractCloudConfig implements BeanFactoryAware {
 	/**
 	 * Get the object containing service and app properties
 	 *  
-	 * @return
 	 */
 	public Properties properties() {
 		return cloud().getCloudProperties();
 	}
-	
+
+	/**
+     * Implementation note: This roundabout way of implementation is required to ensure that
+     * a {@link CloudFactory} bean if created in some other configuration is available, we should use
+     * that.
+	 */
 	@Override
 	public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
 		if (cloudFactory == null) {

spring-service-connector/src/main/java/org/springframework/cloud/service/AbstractCloudServiceConnectorFactory.java

@@ -34,7 +34,6 @@ public abstract class AbstractCloudServiceConnectorFactory<S> extends AbstractFa
 
 	/**
 	 * 
-	 * @param cloud
 	 * @param serviceId Optional service name property. If this property is	null, a unique service of the expected type 
 	 * 					(redis, for example) needs to be bound to the application.
 	 * @param serviceConnectorType