Fix documentation and imports

tocker · tocker · commit 8b9a775ee8e9 · 2015-03-24T13:16:21.000+02:00
diff --git a/README.md b/README.md
@@ -124,7 +124,7 @@ Assuming you have your Cloudinary configuration parameters defined (`cloud_name`
     
 The following example uploads a local JPG to the cloud: 
     
-    cloudinary.uploader().upload("my_picture.jpg", Cloudinary.emptyMap())
+    cloudinary.uploader().upload("my_picture.jpg", ObjectUtils.emptyMap())
         
 The uploaded image is assigned a randomly generated public ID. The image is immediately available for download through a CDN:
 
diff --git a/cloudinary-android/src/main/java/com/cloudinary/android/MultipartUtility.java b/cloudinary-android/src/main/java/com/cloudinary/android/MultipartUtility.java
@@ -74,7 +74,7 @@ public void addFormField(String name, String value) {
 	 * Adds a upload file section to the request
 	 * 
 	 * @param fieldName
-	 *            name attribute in <input type="file" name="..." />
+	 *            name attribute in {@code <input type="file" name="..." />}
 	 * @param uploadFile
 	 *            a File to be uploaded
 	 * @throws IOException
diff --git a/cloudinary-core/src/main/java/com/cloudinary/Configuration.java b/cloudinary-core/src/main/java/com/cloudinary/Configuration.java
@@ -115,7 +115,7 @@ public Configuration(Configuration other) {
 	/**
      * Create a new Configuration from an existing one
      * @param other
-     * @return
+     * @return a new configuration with the arguments supplied by another configuration object
      */
     public static Configuration from(Configuration other) {
         return new Builder().from(other).build();
@@ -127,7 +127,7 @@ public static Configuration from(Configuration other) {
      * Example url: cloudinary://123456789012345:abcdeghijklmnopqrstuvwxyz12@n07t21i7
      *
      * @param cloudinaryUrl configuration url
-     * @return
+     * @return a new configuration with the arguments supplied by the url
      */
     public static Configuration from(String cloudinaryUrl) {
         return from(parseConfigUrl(cloudinaryUrl));
@@ -314,8 +314,8 @@ public Builder setUseRootPath(boolean useRootPath) {
       
         /**
          * Initialize builder from existing {@link Configuration}
-         * @param other
-         * @return
+         * @param other a different configuration object
+         * @return an initialized builder configured with <code>other</code>
          */
         public Builder from(Configuration other) {
             this.cloudName  = other.cloudName;
diff --git a/cloudinary-core/src/main/java/com/cloudinary/Url.java b/cloudinary-core/src/main/java/com/cloudinary/Url.java
@@ -36,9 +36,8 @@ public Url(Cloudinary cloudinary) {
 	private static Pattern identifierPattern = Pattern.compile("^(?:([^/]+)/)??(?:([^/]+)/)??(?:v(\\d+)/)?" + "(?:([^#/]+?)(?:\\.([^.#/]+))?)(?:#([^/]+))?$");
 
 	/**
-	 * Parses a cloudinary identifier of the form:
-	 * [<resource_type>/][<image_type
-	 * >/][v<version>/]<public_id>[.<format>][#<signature>]
+	 * Parses a cloudinary identifier of the form:<br>
+	 * {@code [<resource_type>/][<image_type>/][v<version>/]<public_id>[.<format>][#<signature>]}
 	 */
 	public Url fromIdentifier(String identifier) {
 		Matcher matcher = identifierPattern.matcher(identifier);
diff --git a/cloudinary-core/src/main/java/com/cloudinary/api/ApiResponse.java b/cloudinary-core/src/main/java/com/cloudinary/api/ApiResponse.java
@@ -1,9 +1,10 @@
 package com.cloudinary.api;
 
+import java.text.ParseException;
 import java.util.Map;
 
 @SuppressWarnings("rawtypes")
 public interface ApiResponse extends Map {
-	Map<String, RateLimit> rateLimits() throws java.text.ParseException;
-	RateLimit apiRateLimit() throws java.text.ParseException;
+	Map<String, RateLimit> rateLimits() throws ParseException;
+	RateLimit apiRateLimit() throws ParseException;
 }
diff --git a/cloudinary-core/src/main/java/com/cloudinary/utils/Base64Coder.java b/cloudinary-core/src/main/java/com/cloudinary/utils/Base64Coder.java
@@ -70,7 +70,7 @@ public static String encodeString(String s) {
 	/**
 	 * Encodes a byte array into Base 64 format and breaks the output into lines
 	 * of 76 characters. This method is compatible with
-	 * <code>sun.misc.BASE64Encoder.encodeBuffer(byte[])</code>.
+	 * {@code sun.misc.BASE64Encoder.encodeBuffer(byte[])}.
 	 * 
 	 * @param in
 	 *            An array containing the data bytes to be encoded.
@@ -87,10 +87,10 @@ public static String encodeLines(byte[] in) {
 	 * @param in
 	 *            An array containing the data bytes to be encoded.
 	 * @param iOff
-	 *            Offset of the first byte in <code>in</code> to be processed.
+	 *            Offset of the first byte in {@code in} to be processed.
 	 * @param iLen
-	 *            Number of bytes to be processed in <code>in</code>, starting
-	 *            at <code>iOff</code>.
+	 *            Number of bytes to be processed in {@code in}, starting
+	 *            at {@code iOff}.
 	 * @param lineLen
 	 *            Line length for the output data. Should be a multiple of 4.
 	 * @param lineSeparator
@@ -134,7 +134,7 @@ public static char[] encode(byte[] in) {
 	 * @param in
 	 *            An array containing the data bytes to be encoded.
 	 * @param iLen
-	 *            Number of bytes to process in <code>in</code>.
+	 *            Number of bytes to process in {@code in}.
 	 * @return A character array containing the Base64 encoded data.
 	 */
 	public static char[] encode(byte[] in, int iLen) {
@@ -148,10 +148,10 @@ public static char[] encode(byte[] in, int iLen) {
 	 * @param in
 	 *            An array containing the data bytes to be encoded.
 	 * @param iOff
-	 *            Offset of the first byte in <code>in</code> to be processed.
+	 *            Offset of the first byte in {@code in} to be processed.
 	 * @param iLen
-	 *            Number of bytes to process in <code>in</code>, starting at
-	 *            <code>iOff</code>.
+	 *            Number of bytes to process in {@code in}, starting at
+	 *            {@code iOff}.
 	 * @return A character array containing the Base64 encoded data.
 	 */
 	public static char[] encode(byte[] in, int iOff, int iLen) {
@@ -197,7 +197,7 @@ public static String decodeString(String s) {
 	 * Decodes a byte array from Base64 format and ignores line separators, tabs
 	 * and blanks. CR, LF, Tab and Space characters are ignored in the input
 	 * data. This method is compatible with
-	 * <code>sun.misc.BASE64Decoder.decodeBuffer(String)</code>.
+	 * {@code sun.misc.BASE64Decoder.decodeBuffer(String)}.
 	 * 
 	 * @param s
 	 *            A Base64 String to be decoded.
@@ -251,11 +251,11 @@ public static byte[] decode(char[] in) {
 	 * @param in
 	 *            A character array containing the Base64 encoded data.
 	 * @param iOff
-	 *            Offset of the first character in <code>in</code> to be
+	 *            Offset of the first character in {@code in} to be
 	 *            processed.
 	 * @param iLen
-	 *            Number of characters to process in <code>in</code>, starting
-	 *            at <code>iOff</code>.
+	 *            Number of characters to process in {@code in}, starting
+	 *            at {@code iOff}.
 	 * @return An array containing the decoded data bytes.
 	 * @throws IllegalArgumentException
 	 *             If the input is not valid Base64 encoded data.
diff --git a/cloudinary-core/src/main/java/org/cloudinary/json/JSONObject.java b/cloudinary-core/src/main/java/org/cloudinary/json/JSONObject.java
@@ -1196,7 +1196,7 @@ public JSONObject putOpt(String key, Object value) throws JSONException {
 
     /**
      * Produce a string in double quotes with backslash sequences in all the
-     * right places. A backslash will be inserted within </, producing <\/,
+     * right places. A backslash will be inserted within &lt;/, producing &lt;\/,
      * allowing JSON text to be delivered in HTML. In JSON text, a string cannot
      * contain a control character or an unescaped quote or backslash.
      *
diff --git a/cloudinary-http42/src/main/java/com/cloudinary/http42/ApiStrategy.java b/cloudinary-http42/src/main/java/com/cloudinary/http42/ApiStrategy.java
@@ -6,6 +6,7 @@
 import java.util.Arrays;
 import java.util.Map;
 
+import com.cloudinary.strategies.AbstractApiStrategy;
 import org.apache.http.HttpResponse;
 import org.apache.http.client.methods.HttpDelete;
 import org.apache.http.client.methods.HttpGet;
@@ -30,7 +31,7 @@
 import com.cloudinary.utils.ObjectUtils;
 import com.cloudinary.utils.StringUtils;
 
-public class ApiStrategy extends com.cloudinary.strategies.AbstractApiStrategy  {
+public class ApiStrategy extends AbstractApiStrategy  {
 	
 	
 	@SuppressWarnings({ "rawtypes", "unchecked" })
diff --git a/cloudinary-http42/src/main/java/com/cloudinary/http42/UrlBuilderStrategy.java b/cloudinary-http42/src/main/java/com/cloudinary/http42/UrlBuilderStrategy.java
@@ -1,8 +1,9 @@
 package com.cloudinary.http42;
 
+import com.cloudinary.strategies.AbstractUrlBuilderStrategy;
 import org.apache.http.client.utils.URIBuilder;
 
-public class UrlBuilderStrategy extends com.cloudinary.strategies.AbstractUrlBuilderStrategy {
+public class UrlBuilderStrategy extends AbstractUrlBuilderStrategy {
 	
 	private URIBuilder builder;
 	@Override
diff --git a/cloudinary-http42/src/main/java/com/cloudinary/http42/api/Response.java b/cloudinary-http42/src/main/java/com/cloudinary/http42/api/Response.java
@@ -1,6 +1,7 @@
 package com.cloudinary.http42.api;
 
 import java.text.DateFormat;
+import java.text.ParseException;
 import java.text.SimpleDateFormat;
 import java.util.HashMap;
 import java.util.Map;
@@ -35,7 +36,7 @@ public HttpResponse getRawHttpResponse() {
 	private static final DateFormat RFC1123 = new SimpleDateFormat(
 			RFC1123_PATTERN);
 
-	public Map<String, RateLimit> rateLimits() throws java.text.ParseException {
+	public Map<String, RateLimit> rateLimits() throws ParseException {
 		Header[] headers = this.response.getAllHeaders();
 		Map<String, RateLimit> limits = new HashMap<String, RateLimit>();
 		for (Header header : headers) {
@@ -63,7 +64,7 @@ public Map<String, RateLimit> rateLimits() throws java.text.ParseException {
 		return limits;
 	}
 
-	public RateLimit apiRateLimit() throws java.text.ParseException {
+	public RateLimit apiRateLimit() throws ParseException {
 		return rateLimits().get("Api");
 	}
 }
diff --git a/cloudinary-http42/src/test/java/com/cloudinary/test/ApiTest.java b/cloudinary-http42/src/test/java/com/cloudinary/test/ApiTest.java
@@ -13,11 +13,13 @@
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
 import org.apache.http.conn.ConnectTimeoutException;
+import org.cloudinary.json.JSONArray;
 import org.junit.Before;
 import org.junit.BeforeClass;
 import org.junit.Ignore;
@@ -40,7 +42,7 @@ public class ApiTest {
     public static final String SRC_TEST_IMAGE = "src/test/resources/old_logo.png";
     private Cloudinary cloudinary;
 	private Api api;
-	private static String uniqueTag = String.format("api_test_tag_%d", new java.util.Date().getTime());
+	private static String uniqueTag = String.format("api_test_tag_%d", new Date().getTime());
 
 	@BeforeClass
 	public static void setUpClass() throws IOException {
@@ -207,7 +209,7 @@ public void testResourcesListingStartAt() throws Exception {
 		// should allow listing resources by start date - make sure your clock
 		// is set correctly!!!
 		Thread.sleep(2000L);
-		java.util.Date startAt = new java.util.Date();
+		Date startAt = new Date();
 		Thread.sleep(2000L);
 		Map response = cloudinary.uploader().upload(SRC_TEST_IMAGE, ObjectUtils.emptyMap());
 		ApiResponse listResources = api.resources(ObjectUtils.asMap("type", "upload", "start_at", startAt, "direction", "asc"));
@@ -432,7 +434,7 @@ public void testDeleteAllResources() throws Exception {
 		cloudinary.uploader().upload(SRC_TEST_IMAGE,
 				ObjectUtils.asMap("public_id", "api_test5", "eager", Collections.singletonList(new Transformation().crop("scale").width(2.0))));
 		Map result = api.resource("api_test5", ObjectUtils.emptyMap());
-		assertEquals(1, ((org.cloudinary.json.JSONArray) result.get("derived")).length());
+		assertEquals(1, ((JSONArray) result.get("derived")).length());
 		api.deleteAllResources(ObjectUtils.asMap("keep_original", true));
 		result = api.resource("api_test5", ObjectUtils.emptyMap());
 		// assertEquals(0, ((org.cloudinary.json.JSONArray)
@@ -533,7 +535,7 @@ public void testApiLimits() throws Exception {
 		assertTrue(result2.apiRateLimit().getLimit() > result2.apiRateLimit().getRemaining());
 		assertEquals(result1.apiRateLimit().getLimit(), result2.apiRateLimit().getLimit());
 		assertEquals(result1.apiRateLimit().getReset(), result2.apiRateLimit().getReset());
-		assertTrue(result2.apiRateLimit().getReset().after(new java.util.Date()));
+		assertTrue(result2.apiRateLimit().getReset().after(new Date()));
 	}
 
 	@Test
@@ -567,10 +569,10 @@ public void testGetUploadPreset() throws Exception {
 		assertEquals(Boolean.TRUE, preset.get("unsigned"));
 		Map settings = (Map) preset.get("settings");
 		assertEquals(settings.get("folder"), "folder");
-		Map outTransformation = (Map) ((java.util.ArrayList) settings.get("transformation")).get(0);
+		Map outTransformation = (Map) ((ArrayList) settings.get("transformation")).get(0);
 		assertEquals(outTransformation.get("width"), 100);
 		assertEquals(outTransformation.get("crop"), "scale");
-		Object[] outTags = ((java.util.ArrayList) settings.get("tags")).toArray();
+		Object[] outTags = ((ArrayList) settings.get("tags")).toArray();
 		assertArrayEquals(tags, outTags);
 		Map outContext = (Map) settings.get("context");
 		assertEquals(context, outContext);
@@ -640,11 +642,11 @@ public void testFolderApi() throws Exception {
 		cloudinary.uploader().upload(SRC_TEST_IMAGE, ObjectUtils.asMap("public_id", "test_folder1/test_subfolder1/item"));
 		cloudinary.uploader().upload(SRC_TEST_IMAGE, ObjectUtils.asMap("public_id", "test_folder1/test_subfolder2/item"));
 		Map result = api.rootFolders(null);
-		assertEquals("test_folder1", ((Map) ((org.cloudinary.json.JSONArray) result.get("folders")).get(0)).get("name"));
-		assertEquals("test_folder2", ((Map) ((org.cloudinary.json.JSONArray) result.get("folders")).get(1)).get("name"));
+		assertEquals("test_folder1", ((Map) ((JSONArray) result.get("folders")).get(0)).get("name"));
+		assertEquals("test_folder2", ((Map) ((JSONArray) result.get("folders")).get(1)).get("name"));
 		result = api.subFolders("test_folder1", null);
-		assertEquals("test_folder1/test_subfolder1", ((Map) ((org.cloudinary.json.JSONArray) result.get("folders")).get(0)).get("path"));
-		assertEquals("test_folder1/test_subfolder2", ((Map) ((org.cloudinary.json.JSONArray) result.get("folders")).get(1)).get("path"));
+		assertEquals("test_folder1/test_subfolder1", ((Map) ((JSONArray) result.get("folders")).get(0)).get("path"));
+		assertEquals("test_folder1/test_subfolder2", ((Map) ((JSONArray) result.get("folders")).get(1)).get("path"));
 		try {
 			api.subFolders("test_folder", null);
 		} catch (Exception e) {
diff --git a/cloudinary-http42/src/test/java/com/cloudinary/test/UploaderTest.java b/cloudinary-http42/src/test/java/com/cloudinary/test/UploaderTest.java
@@ -5,6 +5,7 @@
 import static org.junit.Assert.assertTrue;
 import static org.junit.Assume.assumeNotNull;
 
+import java.io.File;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -355,7 +356,7 @@ public void testAutoTaggingRequest() {
     public void testUploadLargeRawFiles()  throws Exception {
     	// support uploading large raw files
         Map response = cloudinary.uploader().uploadLargeRaw("src/test/resources/docx.docx", ObjectUtils.emptyMap());
-        assertEquals((int)(new java.io.File("src/test/resources/docx.docx").length()), response.get("bytes"));
+        assertEquals((int)(new File("src/test/resources/docx.docx").length()), response.get("bytes"));
         assertEquals(Boolean.TRUE, response.get("done"));
     }
 
diff --git a/cloudinary-taglib/src/main/java/com/cloudinary/taglib/CloudinaryImageTag.java b/cloudinary-taglib/src/main/java/com/cloudinary/taglib/CloudinaryImageTag.java
@@ -14,15 +14,24 @@
 import com.cloudinary.*;
 
 /**
- * <cl:img source='test' height='101' width='100' crop="crop" />
- * 
- * Transformation transformation = new Transformation().width(100).height(101).crop("crop");
- * String result = cloudinary.url().transformation(transformation).imageTag("test",
- * Cloudinary.asMap("alt", "my image"));
- * 
- * <img src='http://res.cloudinary.com/test123/image/upload/c_crop,h_101,w_100/test' alt='my image'
- * height='101' width='100'/>
- * 
+ * Generates an image html tag.<br>
+ * For example,<br>
+ * {@code <cl:img source='test' height='101' width='100' crop="crop" />}
+ * <br>is equivalent to:<br>
+ * <pre>{@code
+ * Transformation transformation = new Transformation()
+ *      .width(100)
+ *      .height(101)
+ *      .crop("crop");
+ * String result = cloudinary.url()
+ *      .transformation(transformation)
+ *      .imageTag("test", Cloudinary.asMap("alt", "my image"));
+ * }</pre>
+ * <br>
+ * Both code segments above produce the following tag:<br>
+ * {@code <img src='http://res.cloudinary.com/test123/image/upload/c_crop,h_101,w_100/test' alt='my image'
+ * height='101' width='100'/> }
+ * <br>
  * @author jpollak
  * 
  */
diff --git a/cloudinary-taglib/src/main/java/com/cloudinary/taglib/CloudinaryUrl.java b/cloudinary-taglib/src/main/java/com/cloudinary/taglib/CloudinaryUrl.java
@@ -14,8 +14,10 @@
 import com.cloudinary.*;
 
 /**
- * <cl:url source='test' height='101' width='100' crop="crop" />
- * http://res.cloudinary.com/test123/image/upload/c_crop,h_101,w_100/test
+ * Generates a cloudinary resource url
+ *
+ * <br>For example,<br> {@code <cl:url source='test' height='101' width='100' crop="crop" />}
+ * will produce<br> {@code http://res.cloudinary.com/test123/image/upload/c_crop,h_101,w_100/test}
  *
  */
 public class CloudinaryUrl extends SimpleTagSupport implements DynamicAttributes {

Original file line number	Diff line number	Diff line change
`@@ -74,7 +74,7 @@ public void addFormField(String name, String value) {`
`74`	`74`	`* Adds a upload file section to the request`
`75`	`75`	`*`
`76`	`76`	`* @param fieldName`
`77`		`- * name attribute in <input type="file" name="..." />`
	`77`	`+ * name attribute in {@code <input type="file" name="..." />}`
`78`	`78`	`* @param uploadFile`
`79`	`79`	`* a File to be uploaded`
`80`	`80`	`* @throws IOException`
Original file line number	Diff line number	Diff line change
`@@ -1196,7 +1196,7 @@ public JSONObject putOpt(String key, Object value) throws JSONException {`
`1196`	`1196`
`1197`	`1197`	`/**`
`1198`	`1198`	`* Produce a string in double quotes with backslash sequences in all the`
`1199`		`- * right places. A backslash will be inserted within </, producing <\/,`
	`1199`	`+ * right places. A backslash will be inserted within </, producing <\/,`
`1200`	`1200`	`* allowing JSON text to be delivered in HTML. In JSON text, a string cannot`
`1201`	`1201`	`* contain a control character or an unescaped quote or backslash.`
`1202`	`1202`	`*`