From b149a654e747a2e83f5b8cea092b1b4c6b5ec8cc Mon Sep 17 00:00:00 2001 From: "R. Tyler Croy" Date: Fri, 18 Sep 2015 15:31:15 -0700 Subject: [PATCH] Clean up some javadocs to ameliorate failuresi n travis Somehow the version of the JDK in travis errors with some of these but not locally :( --- .../java/com/github/jrubygradle/jem/Gem.java | 17 +++++++++++++---- .../github/jrubygradle/jem/GemInstaller.java | 16 ++++++++-------- .../jrubygradle/jem/internal/GemInstaller.java | 17 +++++++++++++++-- 3 files changed, 36 insertions(+), 14 deletions(-) diff --git a/src/main/java/com/github/jrubygradle/jem/Gem.java b/src/main/java/com/github/jrubygradle/jem/Gem.java index d66b089..998ebbf 100644 --- a/src/main/java/com/github/jrubygradle/jem/Gem.java +++ b/src/main/java/com/github/jrubygradle/jem/Gem.java @@ -64,7 +64,9 @@ public class Gem { * Take the given argument and produce a {@code Gem} instance * * @param metadata a {@code java.lang.String}, a {@code java.io.File} or a {@code java.util.zip.GZIPInputStream} - * @return + * @return constructed instance of Gem or null if we couldn't process arguments + * @throws JsonProcessingException when the String provided is not JSON + * @throws IOException when the File provided can not be properly read */ public static Gem fromFile(Object metadata) throws JsonProcessingException, IOException { if (metadata instanceof String) { @@ -83,9 +85,10 @@ public class Gem { /** * Output the gemspec stub for this file * - * See + * See: https://github.com/rubygems/rubygems/blob/165030689defe16680b7f336232db62024f49de4/lib/rubygems/specification.rb#L2422-L2512 * - * @return + * @return String representation of the computed .gemspec file + * @throws JsonProcessingException if some attributes could not be properly serialized out to JSON */ public String toRuby() throws JsonProcessingException { String[] specification = { @@ -127,7 +130,13 @@ public class Gem { return builder.toString(); } - /** Convert whatever object we're given into a safe (see: JSON) reprepsentation */ + /** + * Convert whatever object we're given into a safe (see: JSON) reprepsentation + * + * @param value Object to pass to Jackson to create a string representation of + * @return String representation of the value parameter + * @throws JsonProcessingException Exception when the value cannot be JSON serialized + */ protected String sanitize(Object value) throws JsonProcessingException { ObjectMapper mapper = new ObjectMapper(); return mapper.writeValueAsString(value); diff --git a/src/main/java/com/github/jrubygradle/jem/GemInstaller.java b/src/main/java/com/github/jrubygradle/jem/GemInstaller.java index 90cb410..b98ca08 100644 --- a/src/main/java/com/github/jrubygradle/jem/GemInstaller.java +++ b/src/main/java/com/github/jrubygradle/jem/GemInstaller.java @@ -19,8 +19,8 @@ public class GemInstaller { /** * Create an installer with the given installation directory and a single gem * - * @param installDir - * @param gemPath + * @param installDir relative or absoluate path to the installation destination directory + * @param gemPath relative or absolute path to the gem to be installed */ public GemInstaller(String installDir, String gemPath) { this(installDir, new File(gemPath)); @@ -29,8 +29,8 @@ public class GemInstaller { /** * Create an installer with the given installation directory and a single gem * - * @param installDir - * @param gemFile + * @param installDir relative or absoluate path to the installation destination directory + * @param gemFile File object for the gem to be installed */ public GemInstaller(String installDir, File gemFile) { this(installDir, Arrays.asList(gemFile)); @@ -39,8 +39,8 @@ public class GemInstaller { /** * Create an installer with the given installation directory and a list of gems * - * @param installDir - * @param gemPaths + * @param installDir relative or absoluate path to the installation destination directory + * @param gemPaths List of File objects for gems to be installed */ public GemInstaller(String installDir, List gemPaths) { impl = new com.github.jrubygradle.jem.internal.GemInstaller(installDir, gemPaths); @@ -51,7 +51,7 @@ public class GemInstaller { * * Chances are you do not want this constructor, which is largely used for unit testing! * - * @param implementation + * @param implementation An internal GemInstaller implementation to use for the public API */ public GemInstaller(com.github.jrubygradle.jem.internal.GemInstaller implementation) { impl = implementation; @@ -69,7 +69,7 @@ public class GemInstaller { * Install the gems in the configuration installation directory with the given * overwrite setting * - * @param overwriteBehavior + * @param overwriteBehavior Flag to determine what behavior should be taken on overwriting existing gems */ public void install(DuplicateBehavior overwriteBehavior) { impl.install(overwriteBehavior); diff --git a/src/main/java/com/github/jrubygradle/jem/internal/GemInstaller.java b/src/main/java/com/github/jrubygradle/jem/internal/GemInstaller.java index 98a6a06..18ec635 100644 --- a/src/main/java/com/github/jrubygradle/jem/internal/GemInstaller.java +++ b/src/main/java/com/github/jrubygradle/jem/internal/GemInstaller.java @@ -157,7 +157,13 @@ public class GemInstaller { writer.flush(); } - /** Extract the data.tar.gz contents into gems/full-name/* */ + /** + * Extract the data.tar.gz contents into gems/full-name + * + * @param installDir relative or absoluate path to the installation destination directory + * @param dataTarGz instance of the archive from which to extract the gem data + * @param gem Gem instance containing the metadata about the provided dataTarGz archive + */ protected void extractData(File installDir, GenericArchive dataTarGz, Gem gem) { File outputDir = new File(installDir, "gems"); outputDir.mkdirs(); @@ -165,7 +171,14 @@ public class GemInstaller { dataTarGz.as(ExplodedExporter.class).exportExploded(outputDir, gemFullName(gem)); } - /** Extract the executables from the specified bindir */ + /** + * Extract the executables from the specified bindir + * + * @param installDir relative or absoluate path to the installation destination directory + * @param dataTarGz instance of the archive from which to extract the gem executables + * @param gem Gem instance containing the metadata about the provided dataTarGz archive + * @throws Exception catch-all exceptions incurred while attempting to read/write out files + */ protected void extractExecutables(File installDir, GenericArchive dataTarGz, Gem gem) throws Exception { /* * default to "bin" if the bindir isn"t otherwise set, it"s not clear whether