Polish the javadoc in spring-boot-cli

Add missing @param and @return elements

spring-boot-cli/src/main/java/org/springframework/boot/cli/command/Command.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * Copyright 2012-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,41 +33,48 @@ public interface Command {
 
 	/**
 	 * Returns the name of the command.
+	 * @return the command's name
 	 */
 	String getName();
 
 	/**
 	 * Returns a description of the command.
+	 * @return the command's description
 	 */
 	String getDescription();
 
 	/**
 	 * Returns usage help for the command. This should be a simple one-line string
 	 * describing basic usage. e.g. '[options] <file>'. Do not include the name of
 	 * the command in this string.
+	 * @return the command's usage help
 	 */
 	String getUsageHelp();
 
 	/**
 	 * Gets full help text for the command, e.g. a longer description and one line per
 	 * option.
+	 * @return the command's help text
 	 */
 	String getHelp();
 
 	/**
 	 * Returns help for each supported option.
+	 * @return help for each of the command's options
 	 */
 	Collection<OptionHelp> getOptionsHelp();
 
 	/**
 	 * Return some examples for the command.
+	 * @return the command's examples
 	 */
 	Collection<HelpExample> getExamples();
 
 	/**
 	 * Run the command.
 	 * @param args command arguments (this will not include the command itself)
-	 * @throws Exception
+	 * @throws Exception if the command fails
+	 * @return the outcome of the command
 	 */
 	ExitStatus run(String... args) throws Exception;
 

spring-boot-cli/src/main/java/org/springframework/boot/cli/command/CommandException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * Copyright 2012-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -80,7 +80,8 @@ private EnumSet<Option> asEnumSet(Option[] options) {
 	}
 
 	/**
-	 * Returns options a set of options that are understood by the {@link CommandRunner}.
+	 * Returns a set of options that are understood by the {@link CommandRunner}.
+	 * @return the options understood by the runner
 	 */
 	public Set<Option> getOptions() {
 		return Collections.unmodifiableSet(this.options);

spring-boot-cli/src/main/java/org/springframework/boot/cli/command/CommandRunner.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * Copyright 2012-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -61,6 +61,7 @@ public CommandRunner(String name) {
 	/**
 	 * Return the name of the runner or an empty string. Non-empty names will include a
 	 * trailing space character so that they can be used as a prefix.
+	 * @return the name of the runner
 	 */
 	public String getName() {
 		return this.name;
@@ -179,7 +180,7 @@ public int runAndHandleErrors(String... args) {
 			showUsage();
 			return 1;
 		}
-		catch(TestFailedException e) {
+		catch (TestFailedException e) {
 			return 1;
 		}
 		catch (Exception ex) {
@@ -204,7 +205,8 @@ private String[] removeDebugFlags(String[] args) {
 	/**
 	 * Parse the arguments and run a suitable command.
 	 * @param args the arguments
-	 * @throws Exception
+	 * @throws Exception if the command fails
+	 * @return the outcome of the command
 	 */
 	protected ExitStatus run(String... args) throws Exception {
 		if (args.length == 0) {

spring-boot-cli/src/main/java/org/springframework/boot/cli/command/init/InitializrService.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * Copyright 2012-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -69,7 +69,9 @@ protected CloseableHttpClient getHttp() {
 
 	/**
 	 * Generate a project based on the specified {@link ProjectGenerationRequest}
+	 * @param request the generation request
 	 * @return an entity defining the project
+	 * @throws IOException if generation fails
 	 */
 	public ProjectGenerationResponse generate(ProjectGenerationRequest request)
 			throws IOException {
@@ -89,6 +91,9 @@ public ProjectGenerationResponse generate(ProjectGenerationRequest request)
 
 	/**
 	 * Load the {@link InitializrServiceMetadata} at the specified url.
+	 * @param serviceUrl to url of the initializer service
+	 * @return the metadata describing the service
+	 * @throws IOException if the service's metadata cannot be loaded
 	 */
 	public InitializrServiceMetadata loadMetadata(String serviceUrl) throws IOException {
 		CloseableHttpResponse httpResponse = executeInitializrMetadataRetrieval(serviceUrl);

spring-boot-cli/src/main/java/org/springframework/boot/cli/command/init/InitializrServiceMetadata.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * Copyright 2012-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -57,6 +57,7 @@ class InitializrServiceMetadata {
 
 	/**
 	 * Creates a new instance using the specified root {@link JSONObject}.
+	 * @param root the root JSONObject
 	 */
 	public InitializrServiceMetadata(JSONObject root) {
 		this.dependencies = parseDependencies(root);
@@ -75,6 +76,7 @@ public InitializrServiceMetadata(ProjectType defaultProjectType) {
 
 	/**
 	 * Return the dependencies supported by the service.
+	 * @return the supported dependencies
 	 */
 	public Collection<Dependency> getDependencies() {
 		return this.dependencies.values();
@@ -83,21 +85,25 @@ public Collection<Dependency> getDependencies() {
 	/**
 	 * Return the dependency with the specified id or {@code null} if no such dependency
 	 * exists.
+	 * @param id the id
+	 * @return the dependency or {@code null}
 	 */
 	public Dependency getDependency(String id) {
 		return this.dependencies.get(id);
 	}
 
 	/**
 	 * Return the project types supported by the service.
+	 * @return the supported project types
 	 */
 	public Map<String, ProjectType> getProjectTypes() {
 		return this.projectTypes.getContent();
 	}
 
 	/**
-	 * Return the default type to use or {@code null} or the metadata does not define any
+	 * Return the default type to use or {@code null} if the metadata does not define any
 	 * default.
+	 * @return the default project type or {@code null}
 	 */
 	public ProjectType getDefaultType() {
 		if (this.projectTypes.getDefaultItem() != null) {
@@ -112,6 +118,7 @@ public ProjectType getDefaultType() {
 
 	/**
 	 * Returns the defaults applicable to the service.
+	 * @return the defaults of the service
 	 */
 	public Map<String, String> getDefaults() {
 		return this.defaults;

spring-boot-cli/src/main/java/org/springframework/boot/cli/command/init/ProjectGenerationRequest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * Copyright 2012-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -60,8 +60,9 @@ class ProjectGenerationRequest {
 	private String type;
 
 	/**
-	 * The url of the service to use.
+	 * The URL of the service to use.
 	 * @see #DEFAULT_SERVICE_URL
+	 * @return the service URL
 	 */
 	public String getServiceUrl() {
 		return this.serviceUrl;
@@ -73,6 +74,7 @@ public void setServiceUrl(String serviceUrl) {
 
 	/**
 	 * The location of the generated project.
+	 * @return the location of the generated project
 	 */
 	public String getOutput() {
 		return this.output;
@@ -89,8 +91,10 @@ public void setOutput(String output) {
 	}
 
 	/**
-	 * Specify if the project archive should be extract in the output location. If the
-	 * {@link #getOutput() output} ends with "/", the project is extracted automatically.
+	 * Whether or not the project archive should be extracted in the output location. If
+	 * the {@link #getOutput() output} ends with "/", the project is extracted
+	 * automatically.
+	 * @return {@code true} if the archive should be extracted, otherwise {@code false}
 	 */
 	public boolean isExtract() {
 		return this.extract;
@@ -102,6 +106,7 @@ public void setExtract(boolean extract) {
 
 	/**
 	 * The Spring Boot version to use or {@code null} if it should not be customized.
+	 * @return the Spring Boot version of {@code null}
 	 */
 	public String getBootVersion() {
 		return this.bootVersion;
@@ -113,13 +118,15 @@ public void setBootVersion(String bootVersion) {
 
 	/**
 	 * The identifiers of the dependencies to include in the project.
+	 * @return the dependency identifiers
 	 */
 	public List<String> getDependencies() {
 		return this.dependencies;
 	}
 
 	/**
 	 * The Java version to use or {@code null} if it should not be customized.
+	 * @return the Java version or {@code null}
 	 */
 	public String getJavaVersion() {
 		return this.javaVersion;
@@ -131,6 +138,7 @@ public void setJavaVersion(String javaVersion) {
 
 	/**
 	 * The packaging type or {@code null} if it should not be customized.
+	 * @return the packaging type or {@code null}
 	 */
 	public String getPackaging() {
 		return this.packaging;
@@ -143,6 +151,7 @@ public void setPackaging(String packaging) {
 	/**
 	 * The build type to use. Ignored if a type is set. Can be used alongside the
 	 * {@link #getFormat() format} to identify the type to use.
+	 * @return the build type
 	 */
 	public String getBuild() {
 		return this.build;
@@ -155,6 +164,7 @@ public void setBuild(String build) {
 	/**
 	 * The project format to use. Ignored if a type is set. Can be used alongside the
 	 * {@link #getBuild() build} to identify the type to use.
+	 * @return the project format
 	 */
 	public String getFormat() {
 		return this.format;
@@ -165,7 +175,8 @@ public void setFormat(String format) {
 	}
 
 	/**
-	 * Specify if the type should be detected based on the build and format value.
+	 * Whether or not the type should be detected based on the build and format value.
+	 * @return {@code true} if type detection will be performed, otherwise {@code false}
 	 */
 	public boolean isDetectType() {
 		return this.detectType;
@@ -178,6 +189,7 @@ public void setDetectType(boolean detectType) {
 	/**
 	 * The type of project to generate. Should match one of the advertized type that the
 	 * service supports. If not set, the default is retrieved from the service metadata.
+	 * @return the project type
 	 */
 	public String getType() {
 		return this.type;
@@ -188,7 +200,9 @@ public void setType(String type) {
 	}
 
 	/**
-	 * Generates the URL to use to generate a project represented by this request
+	 * Generates the URI to use to generate a project represented by this request
+	 * @param metadata the metadata that describes the service
+	 * @return the project generation URI
 	 */
 	URI generateUrl(InitializrServiceMetadata metadata) {
 		try {

spring-boot-cli/src/main/java/org/springframework/boot/cli/command/init/ProjectGenerationResponse.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * Copyright 2012-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -38,13 +38,15 @@ public ProjectGenerationResponse(ContentType contentType) {
 
 	/**
 	 * Return the {@link ContentType} of this instance
+	 * @return the content type
 	 */
 	public ContentType getContentType() {
 		return this.contentType;
 	}
 
 	/**
 	 * The generated project archive or file.
+	 * @return the content
 	 */
 	public byte[] getContent() {
 		return this.content;
@@ -57,6 +59,7 @@ public void setContent(byte[] content) {
 	/**
 	 * The preferred file name to use to store the entity on disk or {@code null} if no
 	 * preferred value has been set.
+	 * @return the file name, or {@code null}
 	 */
 	public String getFileName() {
 		return this.fileName;

spring-boot-cli/src/main/java/org/springframework/boot/cli/command/init/ServiceCapabilitiesReportGenerator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * Copyright 2012-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,7 +24,6 @@
 import java.util.List;
 import java.util.Map;
 
-import org.apache.http.impl.client.CloseableHttpClient;
 import org.codehaus.plexus.util.StringUtils;
 
 /**
@@ -40,7 +39,8 @@ class ServiceCapabilitiesReportGenerator {
 	private final InitializrService initializrService;
 
 	/**
-	 * Creates an instance using the specified {@link CloseableHttpClient}.
+	 * Creates an instance using the specified {@link InitializrService}.
+	 * @param initializrService the initialzr service
 	 */
 	ServiceCapabilitiesReportGenerator(InitializrService initializrService) {
 		this.initializrService = initializrService;
@@ -49,6 +49,9 @@ class ServiceCapabilitiesReportGenerator {
 	/**
 	 * Generate a report for the specified service. The report contains the available
 	 * capabilities as advertized by the root endpoint.
+	 * @param url the url of the service
+	 * @return the report that describes the service
+	 * @throws IOException if the report cannot be generated
 	 */
 	public String generate(String url) throws IOException {
 		InitializrServiceMetadata metadata = this.initializrService.loadMetadata(url);

spring-boot-cli/src/main/java/org/springframework/boot/cli/command/options/OptionHelp.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2014 the original author or authors.
+ * Copyright 2012-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,11 +27,13 @@ public interface OptionHelp {
 
 	/**
 	 * Returns the set of options that are mutually synonymous.
+	 * @return the options
 	 */
 	Set<String> getOptions();
 
 	/**
 	 * Returns usage help for the option.
+	 * @return the usage help
 	 */
 	String getUsageHelp();