Fix JavaDoc errors

3breadt · Nov 17, 2014 · 8de9dd8 · 8de9dd8
1 parent de936e7
commit 8de9dd8
Show file tree

Hide file tree

Showing 10 changed files with 82 additions and 92 deletions.
diff --git a/dd-plist.iml b/dd-plist.iml
@@ -1,16 +1,15 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<module org.jetbrains.idea.maven.project.MavenProjectsManager.isMavenModule="true" type="JAVA_MODULE" version="4">
-  <component name="NewModuleRootManager" LANGUAGE_LEVEL="JDK_1_5" inherit-compiler-output="false">
-    <output url="file://$MODULE_DIR$/target/classes" />
-    <output-test url="file://$MODULE_DIR$/target/test-classes" />
-    <content url="file://$MODULE_DIR$">
-      <sourceFolder url="file://$MODULE_DIR$/src/main/java" isTestSource="false" />
-      <sourceFolder url="file://$MODULE_DIR$/src/test/java" isTestSource="true" />
-      <excludeFolder url="file://$MODULE_DIR$/target" />
-    </content>
-    <orderEntry type="inheritedJdk" />
-    <orderEntry type="sourceFolder" forTests="false" />
-    <orderEntry type="library" scope="TEST" name="Maven: junit:junit:3.8.1" level="project" />
-  </component>
-</module>
-
+<?xml version="1.0" encoding="UTF-8"?>
+<module org.jetbrains.idea.maven.project.MavenProjectsManager.isMavenModule="true" type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" LANGUAGE_LEVEL="JDK_1_5" inherit-compiler-output="false">
+    <output url="file://$MODULE_DIR$/target/classes" />
+    <output-test url="file://$MODULE_DIR$/target/test-classes" />
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src/main/java" isTestSource="false" />
+      <sourceFolder url="file://$MODULE_DIR$/src/test/java" isTestSource="true" />
+      <excludeFolder url="file://$MODULE_DIR$/target" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="TEST" name="Maven: junit:junit:3.8.1" level="project" />
+  </component>
+</module>
diff --git a/pom.xml b/pom.xml
@@ -8,7 +8,7 @@
 	<groupId>com.googlecode.plist</groupId>
 	<artifactId>dd-plist</artifactId>
 	<packaging>jar</packaging>
-	<version>1.11</version>
+	<version>1.13</version>
 	<name>dd-plist</name>
 	<url>http://plist.googlecode.com</url>
 	<description>

diff --git a/src/main/java/com/dd/plist/ASCIIPropertyListParser.java b/src/main/java/com/dd/plist/ASCIIPropertyListParser.java
@@ -37,20 +37,22 @@
 import java.util.List;
 
 /**
+ * <p>
  * Parser for ASCII property lists. Supports Apple OS X/iOS and GnuStep/NeXTSTEP format.
  * This parser is based on the recursive descent paradigm, but the underlying grammar
  * is not explicitely defined.
- * <p/>
+ * </p>
+ * <p>
  * Resources on ASCII property list format:
+ * </p>
  * <ul>
- * <li><a href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html>
+ * <li><a href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html">
  * Property List Programming Guide - Old-Style ASCII Property Lists
  * </a></li>
  * <li><a href="http://www.gnustep.org/resources/documentation/Developer/Base/Reference/NSPropertyList.html">
  * GnuStep - NSPropertyListSerialization class documentation
  * </a></li>
  * </ul>
- *
  * @author Daniel Dreibrodt
  */
 public class ASCIIPropertyListParser {
@@ -59,8 +61,9 @@ public class ASCIIPropertyListParser {
      * Parses an ASCII property list file.
      *
      * @param f The ASCII property list file.
-     * @return The root object of the property list. This is usally a NSDictionary but can also be a NSArray.
-     * @throws Exception When an error occurs during parsing.
+     * @return The root object of the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws java.text.ParseException When an error occurs during parsing.
+     * @throws java.io.IOException When an error occured while reading from the input stream.
      */
     public static NSObject parse(File f) throws IOException, ParseException {
         return parse(new FileInputStream(f));
@@ -70,8 +73,9 @@ public static NSObject parse(File f) throws IOException, ParseException {
      * Parses an ASCII property list from an input stream.
      *
      * @param in The input stream that points to the property list's data.
-     * @return The root object of the property list. This is usally a NSDictionary but can also be a NSArray.
-     * @throws Exception When an error occurs during parsing.
+     * @return The root object of the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws java.text.ParseException When an error occurs during parsing.
+     * @throws java.io.IOException When an error occured while reading from the input stream.
      */
     public static NSObject parse(InputStream in) throws ParseException, IOException {
         byte[] buf = PropertyListParser.readAll(in);
@@ -83,8 +87,8 @@ public static NSObject parse(InputStream in) throws ParseException, IOException
      * Parses an ASCII property list from a byte array.
      *
      * @param bytes The ASCII property list data.
-     * @return The root object of the property list. This is usally a NSDictionary but can also be a NSArray.
-     * @throws Exception When an error occurs during parsing.
+     * @return The root object of the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws ParseException When an error occurs during parsing.
      */
     public static NSObject parse(byte[] bytes) throws ParseException {
         ASCIIPropertyListParser parser = new ASCIIPropertyListParser(bytes);
@@ -571,7 +575,8 @@ private String parseQuotedString() throws ParseException {
      *
      * @param s The escaped string according to the ASCII property list format, without leading and trailing quotation marks.
      * @return The unescaped string in UTF-8 or ASCII format, depending on the contained characters.
-     * @throws Exception If the string could not be properly parsed.
+     * @throws java.io.UnsupportedEncodingException If the en-/decoder for the UTF-8 or ASCII encoding could not be loaded
+     * @throws java.nio.charset.CharacterCodingException If the string is encoded neither in ASCII nor in UTF-8
      */
     public static synchronized String parseQuotedString(String s) throws UnsupportedEncodingException, CharacterCodingException {
         List<Byte> strBytes = new LinkedList<Byte>();

diff --git a/src/main/java/com/dd/plist/Base64.java b/src/main/java/com/dd/plist/Base64.java
@@ -26,37 +26,38 @@
 /**
  * <p>Encodes and decodes to and from Base64 notation.</p>
  * <p>Homepage: <a href="http://iharder.net/base64">http://iharder.net/base64</a>.</p>
- * <p/>
+ * 
  * <p>Example:</p>
- * <p/>
+ *
  * <code>String encoded = Base64.encode( myByteArray );</code>
- * <br />
+ *
  * <code>byte[] myByteArray = Base64.decode( encoded );</code>
- * <p/>
+ * 
  * <p>The <tt>options</tt> parameter, which appears in a few places, is used to pass
  * several pieces of information to the encoder. In the "higher level" methods such as
  * encodeBytes( bytes, options ) the options parameter can be used to indicate such
  * things as first gzipping the bytes before encoding them, not inserting linefeeds,
  * and encoding using the URL-safe and Ordered dialects.</p>
- * <p/>
+ * 
  * <p>Note, according to <a href="http://www.faqs.org/rfcs/rfc3548.html">RFC3548</a>,
  * Section 2.1, implementations should not add line feeds unless explicitly told
  * to do so. I've got Base64 set to this behavior now, although earlier versions
  * broke lines by default.</p>
- * <p/>
+ * 
  * <p>The constants defined in Base64 can be OR-ed together to combine options, so you
  * might make a call like this:</p>
- * <p/>
+ * 
  * <code>String encoded = Base64.encodeBytes( mybytes, Base64.GZIP | Base64.DO_BREAK_LINES );</code>
  * <p>to compress the data before encoding it and then making the output have newline characters.</p>
  * <p>Also...</p>
  * <code>String encoded = Base64.encodeBytes( crazyString.getBytes() );</code>
- * <p/>
- * <p/>
- * <p/>
+ * 
+ * 
+ * 
  * <p>
  * Change Log:
  * </p>
+ *
  * <ul>
  * <li>v2.3.7 - Fixed subtle bug when base 64 input stream contained the
  * value 01111111, which is an invalid base 64 character but should not
@@ -129,7 +130,7 @@
  * Special thanks to Jim Kellerman at <a href="http://www.powerset.com/">http://www.powerset.com/</a>
  * for contributing the new Base64 dialects.
  * </li>
- * <p/>
+ * 
  * <li>v2.1 - Cleaned up javadoc comments and unused variables and methods. Added
  * some convenience methods for reading and writing to and from files.</li>
  * <li>v2.0.2 - Now specifies UTF-8 encoding in places where the code fails on systems
@@ -157,7 +158,7 @@
  * <li>v1.3.4 - Fixed when "improperly padded stream" error was thrown at the wrong time.</li>
  * <li>v1.3.3 - Fixed I/O streams which were totally messed up.</li>
  * </ul>
- * <p/>
+ *
  * <p>
  * I am placing this code in the Public Domain. Do with it as you will.
  * This software comes with no guarantees or warranties but with
@@ -640,13 +641,13 @@ public static void encode(java.nio.ByteBuffer raw, java.nio.CharBuffer encoded)
     /**
      * Serializes an object and returns the Base64-encoded
      * version of that serialized object.
-     * <p/>
+     * 
      * <p>As of v 2.3, if the object
      * cannot be serialized or there is another error,
      * the method will throw an java.io.IOException. <b>This is new to v2.3!</b>
      * In earlier versions, it just returned a null value, but
      * in retrospect that's a pretty poor way to handle it.</p>
-     * <p/>
+     * 
      * The object is not GZip-compressed before being encoded.
      *
      * @param serializableObject The object to encode
@@ -664,22 +665,22 @@ public static String encodeObject(java.io.Serializable serializableObject)
     /**
      * Serializes an object and returns the Base64-encoded
      * version of that serialized object.
-     * <p/>
+     * 
      * <p>As of v 2.3, if the object
      * cannot be serialized or there is another error,
      * the method will throw an java.io.IOException. <b>This is new to v2.3!</b>
      * In earlier versions, it just returned a null value, but
      * in retrospect that's a pretty poor way to handle it.</p>
-     * <p/>
+     * 
      * The object is not GZip-compressed before being encoded.
-     * <p/>
+     * 
      * Example options:<pre>
      *   GZIP: gzip-compresses object before encoding it.
      *   DO_BREAK_LINES: break lines at 76 characters
      * </pre>
-     * <p/>
+     * 
      * Example: <code>encodeObject( myObj, Base64.GZIP )</code> or
-     * <p/>
+     * 
      * Example: <code>encodeObject( myObj, Base64.GZIP | Base64.DO_BREAK_LINES )</code>
      *
      * @param serializableObject The object to encode
@@ -790,8 +791,8 @@ public static String encodeBytes(byte[] source) {
      * Example: <code>encodeBytes( myData, Base64.GZIP )</code> or
      * <p>
      * Example: <code>encodeBytes( myData, Base64.GZIP | Base64.DO_BREAK_LINES )</code>
-     * <p/>
-     * <p/>
+     * 
+     * 
      * <p>As of v 2.3, if there is an error with the GZIP stream,
      * the method will throw an java.io.IOException. <b>This is new to v2.3!</b>
      * In earlier versions, it just returned a null value, but
@@ -814,7 +815,7 @@ public static String encodeBytes(byte[] source, int options) throws java.io.IOEx
     /**
      * Encodes a byte array into Base64 notation.
      * Does not GZip-compress data.
-     * <p/>
+     * 
      * <p>As of v 2.3, if there is an error,
      * the method will throw an java.io.IOException. <b>This is new to v2.3!</b>
      * In earlier versions, it just returned a null value, but
@@ -855,8 +856,8 @@ public static String encodeBytes(byte[] source, int off, int len) {
      * Example: <code>encodeBytes( myData, Base64.GZIP )</code> or
      * <p>
      * Example: <code>encodeBytes( myData, Base64.GZIP | Base64.DO_BREAK_LINES )</code>
-     * <p/>
-     * <p/>
+     * 
+     * 
      * <p>As of v 2.3, if there is an error with the GZIP stream,
      * the method will throw an java.io.IOException. <b>This is new to v2.3!</b>
      * In earlier versions, it just returned a null value, but
@@ -1444,7 +1445,7 @@ public Class<?> resolveClass(java.io.ObjectStreamClass streamClass)
 
     /**
      * Convenience method for encoding data to a file.
-     * <p/>
+     * 
      * <p>As of v 2.3, if there is a error,
      * the method will throw an java.io.IOException. <b>This is new to v2.3!</b>
      * In earlier versions, it just returned false, but
@@ -1484,7 +1485,7 @@ public static void encodeToFile(byte[] dataToEncode, String filename)
 
     /**
      * Convenience method for decoding data to a file.
-     * <p/>
+     * 
      * <p>As of v 2.3, if there is a error,
      * the method will throw an java.io.IOException. <b>This is new to v2.3!</b>
      * In earlier versions, it just returned false, but
@@ -1520,7 +1521,7 @@ public static void decodeToFile(String dataToDecode, String filename)
     /**
      * Convenience method for reading a base64-encoded
      * file and decoding it.
-     * <p/>
+     * 
      * <p>As of v 2.3, if there is a error,
      * the method will throw an java.io.IOException. <b>This is new to v2.3!</b>
      * In earlier versions, it just returned false, but
@@ -1581,7 +1582,7 @@ public static byte[] decodeFromFile(String filename)
     /**
      * Convenience method for reading a binary file
      * and base64-encoding it.
-     * <p/>
+     * 
      * <p>As of v 2.3, if there is a error,
      * the method will throw an java.io.IOException. <b>This is new to v2.3!</b>
      * In earlier versions, it just returned false, but
@@ -1729,13 +1730,13 @@ public B64InputStream(java.io.InputStream in) {
         /**
          * Constructs a {@link com.dd.plist.Base64.B64InputStream} in
          * either ENCODE or DECODE mode.
-         * <p/>
+         * 
          * Valid options:<pre>
          *   ENCODE or DECODE: Encode or Decode as data is read.
          *   DO_BREAK_LINES: break lines at 76 characters
-         *     (only meaningful when encoding)</i>
+         *     (only meaningful when encoding)
          * </pre>
-         * <p/>
+         * 
          * Example: <code>new Base64.B64InputStream( in, Base64.DECODE )</code>
          *
          * @param in      the <tt>java.io.InputStream</tt> from which to read data.
@@ -1940,13 +1941,13 @@ public B64OutputStream(java.io.OutputStream out) {
         /**
          * Constructs a {@link com.dd.plist.Base64.B64OutputStream} in
          * either ENCODE or DECODE mode.
-         * <p/>
+         * 
          * Valid options:<pre>
          *   ENCODE or DECODE: Encode or Decode as data is read.
          *   DO_BREAK_LINES: don't break lines at 76 characters
-         *     (only meaningful when encoding)</i>
+         *     (only meaningful when encoding)
          * </pre>
-         * <p/>
+         * 
          * Example: <code>new Base64.B64OutputStream( out, Base64.ENCODE )</code>
          *
          * @param out     the <tt>java.io.B64OutputStream</tt> to which data will be written.

diff --git a/src/main/java/com/dd/plist/BinaryPropertyListParser.java b/src/main/java/com/dd/plist/BinaryPropertyListParser.java
@@ -33,7 +33,7 @@
  * Parses property lists that are in Apple's binary format.
  * Use this class when you are sure about the format of the property list.
  * Otherwise use the PropertyListParser class.
- * <p/>
+ *
  * Parsing is done by calling the static <code>parse</code> methods.
  *
  * @author Daniel Dreibrodt
@@ -85,8 +85,8 @@ protected BinaryPropertyListParser() {
      * Parses a binary property list from a byte array.
      *
      * @param data The binary property list's data.
-     * @return The root object of the property list. This is usally a NSDictionary but can also be a NSArray.
-     * @throws Exception When an error occurs during parsing.
+     * @return The root object of the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws PropertyListFormatException When the property list's format could not be parsed.
      */
     public static NSObject parse(byte[] data) throws IOException, PropertyListFormatException {
         BinaryPropertyListParser parser = new BinaryPropertyListParser();
@@ -97,8 +97,8 @@ public static NSObject parse(byte[] data) throws IOException, PropertyListFormat
      * Parses a binary property list from a byte array.
      *
      * @param data The binary property list's data.
-     * @return The root object of the property list. This is usally a NSDictionary but can also be a NSArray.
-     * @throws Exception When an error occurs during parsing.
+     * @return The root object of the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws PropertyListFormatException When the property list's format could not be parsed.
      */
     private NSObject doParse(byte[] data) throws IOException, PropertyListFormatException {
         bytes = data;
@@ -157,8 +157,8 @@ private NSObject doParse(byte[] data) throws IOException, PropertyListFormatExce
      * Parses a binary property list from an input stream.
      *
      * @param is The input stream that points to the property list's data.
-     * @return The root object of the property list. This is usally a NSDictionary but can also be a NSArray.
-     * @throws Exception When an error occurs during parsing.
+     * @return The root object of the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws PropertyListFormatException When the property list's format could not be parsed.
      */
     public static NSObject parse(InputStream is) throws IOException, PropertyListFormatException {
         //Read all bytes into a list
@@ -171,8 +171,8 @@ public static NSObject parse(InputStream is) throws IOException, PropertyListFor
      * Parses a binary property list file.
      *
      * @param f The binary property list file
-     * @return The root object of the property list. This is usally a NSDictionary but can also be a NSArray.
-     * @throws Exception When an error occurs during parsing.
+     * @return The root object of the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws PropertyListFormatException When the property list's format could not be parsed.
      */
     public static NSObject parse(File f) throws IOException, PropertyListFormatException {
         if (f.length() > Runtime.getRuntime().freeMemory()) {
@@ -189,7 +189,7 @@ public static NSObject parse(File f) throws IOException, PropertyListFormatExcep
      *
      * @param obj The object ID.
      * @return The parsed object.
-     * @throws java.lang.Exception When an error occurs during parsing.
+     * @throws PropertyListFormatException When the property list's format could not be parsed.
      */
     private NSObject parseObject(int obj) throws IOException, PropertyListFormatException {
         int offset = offsetTable[obj];

diff --git a/src/main/java/com/dd/plist/NSDictionary.java b/src/main/java/com/dd/plist/NSDictionary.java
@@ -35,7 +35,7 @@
 /**
  * A NSDictionary is a collection of keys and values, essentially a Hashtable.
  * The keys are simple Strings whereas the values can be any kind of NSObject.
- * <p/>
+ *
  * You can access the keys through the function <code>allKeys()</code>. Access
  * to the objects stored for each key is given through the function
  * <code>objectoForKey(String key)</code>.