Fix all JavaDoc warnings

Author: 3breadt

pom.xml

@@ -8,7 +8,7 @@
 	<groupId>com.googlecode.plist</groupId>
 	<artifactId>dd-plist</artifactId>
 	<packaging>jar</packaging>
-	<version>1.15</version>
+	<version>1.16</version>
 	<name>dd-plist</name>
 	<url>http://plist.googlecode.com</url>
 	<description>

src/main/java/com/dd/plist/Base64.java

@@ -1161,6 +1161,7 @@ else if (source[srcOffset + 3] == EQUALS_SIGN) {
      * @param source The Base64 encoded data
      * @return decoded data
      * @since 2.3.1
+     * @throws java.io.IOException If bogus characters are contained in the input
      */
     public static byte[] decode(byte[] source)
             throws java.io.IOException {

src/main/java/com/dd/plist/BinaryPropertyListParser.java

@@ -23,10 +23,7 @@
 
 package com.dd.plist;
 
-import java.io.File;
-import java.io.FileInputStream;
-import java.io.IOException;
-import java.io.InputStream;
+import java.io.*;
 import java.math.BigInteger;
 
 /**
@@ -83,8 +80,9 @@ protected BinaryPropertyListParser() {
      * @param data The binary property list's data.
      * @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.
+     * @throws java.io.UnsupportedEncodingException When a NSString object could not be decoded.
      */
-    public static NSObject parse(byte[] data) throws IOException, PropertyListFormatException {
+    public static NSObject parse(byte[] data) throws PropertyListFormatException, UnsupportedEncodingException {
         BinaryPropertyListParser parser = new BinaryPropertyListParser();
         return parser.doParse(data);
     }
@@ -95,8 +93,9 @@ public static NSObject parse(byte[] data) throws IOException, PropertyListFormat
      * @param data The binary property list's data.
      * @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.
+     * @throws java.io.UnsupportedEncodingException When a NSString object could not be decoded.
      */
-    private NSObject doParse(byte[] data) throws IOException, PropertyListFormatException {
+    private NSObject doParse(byte[] data) throws PropertyListFormatException, UnsupportedEncodingException {
         bytes = data;
         String magic = new String(copyOfRange(bytes, 0, 8));
         if (!magic.startsWith("bplist")) {
@@ -149,6 +148,7 @@ private NSObject doParse(byte[] data) throws IOException, PropertyListFormatExce
      * @param is The input stream that points to the property list's data.
      * @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.
+     * @throws java.io.IOException When a NSString object could not be decoded or an InputStream IO error occurs.
      */
     public static NSObject parse(InputStream is) throws IOException, PropertyListFormatException {
         byte[] buf = PropertyListParser.readAll(is);
@@ -161,6 +161,7 @@ public static NSObject parse(InputStream is) throws IOException, PropertyListFor
      * @param f The binary property list file
      * @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.
+     * @throws java.io.UnsupportedEncodingException When a NSString object could not be decoded or a file IO error occurs.
      */
     public static NSObject parse(File f) throws IOException, PropertyListFormatException {
         return parse(new FileInputStream(f));
@@ -175,8 +176,9 @@ public static NSObject parse(File f) throws IOException, PropertyListFormatExcep
      * @param obj The object ID.
      * @return The parsed object.
      * @throws PropertyListFormatException When the property list's format could not be parsed.
+     * @throws java.io.UnsupportedEncodingException When a NSString object could not be decoded.
      */
-    private NSObject parseObject(int obj) throws IOException, PropertyListFormatException {
+    private NSObject parseObject(int obj) throws PropertyListFormatException, UnsupportedEncodingException {
         int offset = offsetTable[obj];
         byte type = bytes[offset];
         int objType = (type & 0xF0) >> 4; //First  4 bits

src/main/java/com/dd/plist/BinaryPropertyListWriter.java

@@ -91,7 +91,8 @@ private static int getMinimumRequiredVersion(NSObject root) {
      *
      * @param file the file to write to
      * @param root the source of the data to write to the file
-     * @throws IOException
+     * @throws IOException When an IO error occurs while writing to the file or the object structure contains
+     *                     data that cannot be saved.
      */
     public static void write(File file, NSObject root) throws IOException {
         OutputStream out = new FileOutputStream(file);
@@ -104,7 +105,8 @@ public static void write(File file, NSObject root) throws IOException {
      *
      * @param out  the stream to write to
      * @param root the source of the data to write to the stream
-     * @throws IOException
+     * @throws IOException When an IO error occurs while writing to the stream or the object structure contains
+     *                     data that cannot be saved.
      */
     public static void write(OutputStream out, NSObject root) throws IOException {
         int minVersion = getMinimumRequiredVersion(root);
@@ -123,7 +125,8 @@ public static void write(OutputStream out, NSObject root) throws IOException {
      *
      * @param root The root object of the property list
      * @return The byte array containing the serialized property list
-     * @throws IOException
+     * @throws IOException When an IO error occurs while writing to the stream or the object structure contains
+     *                     data that cannot be saved.
      */
     public static byte[] writeToArray(NSObject root) throws IOException {
         ByteArrayOutputStream bout = new ByteArrayOutputStream();
@@ -147,7 +150,8 @@ public static byte[] writeToArray(NSObject root) throws IOException {
      * Creates a new binary property list writer
      *
      * @param outStr The output stream into which the binary property list will be written
-     * @throws IOException If an error occured while writing to the stream
+     * @throws IOException When an IO error occurs while writing to the stream or the object structure contains
+     *                     data that cannot be saved.
      */
     BinaryPropertyListWriter(OutputStream outStr) throws IOException {
         out = new BufferedOutputStream(outStr);

src/main/java/com/dd/plist/NSObject.java

@@ -77,6 +77,8 @@ void assignIDs(BinaryPropertyListWriter out) {
      * Generates the binary representation of the object.
      *
      * @param out The output stream to serialize the object to.
+     * @throws java.io.IOException When an IO error occurs while writing to the stream or the object structure contains
+     *                             data that cannot be saved.
      */
     abstract void toBinary(BinaryPropertyListWriter out) throws IOException;
 

src/main/java/com/dd/plist/NSSet.java

@@ -78,6 +78,7 @@ public NSSet(NSObject... objects) {
     /**
      * Create a set and fill it with the given objects.
      *
+     * @param ordered Indicates whether the created set should be ordered or unordered.
      * @param objects The objects to populate the set.
      * @see java.util.LinkedHashSet
      * @see java.util.TreeSet

src/main/java/com/dd/plist/NSString.java

@@ -43,8 +43,8 @@ public class NSString extends NSObject implements Comparable<Object> {
      *
      * @param bytes    The binary representation.
      * @param encoding The encoding of the binary representation, the name of a supported charset.
-     * @throws UnsupportedEncodingException
-     * @see java.lang.String
+     * @throws UnsupportedEncodingException When the given encoding is not supported by the JRE.
+     * @see java.lang.String#String(byte[], String)
      */
     public NSString(byte[] bytes, String encoding) throws UnsupportedEncodingException {
         content = new String(bytes, encoding);

src/main/java/com/dd/plist/PropertyListParser.java

@@ -133,6 +133,8 @@ private static int determineType(InputStream is) throws IOException {
      * a maximum count.
      *
      * @param in  The InputStream pointing to the data that should be stored in the array.
+     * @return An array containing all bytes that were read from the input stream.
+     * @throws java.io.IOException When an IO error while reading from the input stream.
      */
     protected static byte[] readAll(InputStream in) throws IOException {
         ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
@@ -151,6 +153,12 @@ protected static byte[] readAll(InputStream in) throws IOException {
      *
      * @param filePath Path to the property list file.
      * @return The root object in the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws javax.xml.parsers.ParserConfigurationException If a document builder for parsing a XML property list
+     *                                                        could not be created. This should not occur.
+     * @throws java.io.IOException If any IO error occurs while reading the file.
+     * @throws org.xml.sax.SAXException If any parse error occurs.
+     * @throws com.dd.plist.PropertyListFormatException If the given property list has an invalid format.
+     * @throws java.text.ParseException If a date string could not be parsed.
      */
     public static NSObject parse(String filePath) throws ParserConfigurationException, ParseException, SAXException, PropertyListFormatException, IOException {
         return parse(new File(filePath));
@@ -161,6 +169,12 @@ public static NSObject parse(String filePath) throws ParserConfigurationExceptio
      *
      * @param f The property list file.
      * @return The root object in the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws javax.xml.parsers.ParserConfigurationException If a document builder for parsing a XML property list
+     *                                                        could not be created. This should not occur.
+     * @throws java.io.IOException If any IO error occurs while reading the file.
+     * @throws org.xml.sax.SAXException If any parse error occurs.
+     * @throws com.dd.plist.PropertyListFormatException If the given property list has an invalid format.
+     * @throws java.text.ParseException If a date string could not be parsed.
      */
     public static NSObject parse(File f) throws IOException, PropertyListFormatException, ParseException, ParserConfigurationException, SAXException {
         FileInputStream fis = new FileInputStream(f);
@@ -183,6 +197,12 @@ public static NSObject parse(File f) throws IOException, PropertyListFormatExcep
      *
      * @param bytes The property list data as a byte array.
      * @return The root object in the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws javax.xml.parsers.ParserConfigurationException If a document builder for parsing a XML property list
+     *                                                        could not be created. This should not occur.
+     * @throws java.io.IOException If any IO error occurs while reading the byte array.
+     * @throws org.xml.sax.SAXException If any parse error occurs.
+     * @throws com.dd.plist.PropertyListFormatException If the given property list has an invalid format.
+     * @throws java.text.ParseException If a date string could not be parsed.
      */
     public static NSObject parse(byte[] bytes) throws IOException, PropertyListFormatException, ParseException, ParserConfigurationException, SAXException {
         switch(determineType(bytes)) {
@@ -202,6 +222,12 @@ public static NSObject parse(byte[] bytes) throws IOException, PropertyListForma
      *
      * @param is The InputStream delivering the property list data.
      * @return The root object of the property list. This is usually a NSDictionary but can also be a NSArray.
+     * @throws javax.xml.parsers.ParserConfigurationException If a document builder for parsing a XML property list
+     *                                                        could not be created. This should not occur.
+     * @throws java.io.IOException If any IO error occurs while reading the input stream.
+     * @throws org.xml.sax.SAXException If any parse error occurs.
+     * @throws com.dd.plist.PropertyListFormatException If the given property list has an invalid format.
+     * @throws java.text.ParseException If a date string could not be parsed.
      */
     public static NSObject parse(InputStream is) throws IOException, PropertyListFormatException, ParseException, ParserConfigurationException, SAXException {
         return parse(readAll(is));
@@ -242,6 +268,13 @@ public static void saveAsXML(NSObject root, OutputStream out) throws IOException
      *
      * @param in  The source file.
      * @param out The target file.
+     *
+     * @throws javax.xml.parsers.ParserConfigurationException If a document builder for parsing a XML property list
+     *                                                        could not be created. This should not occur.
+     * @throws java.io.IOException If any IO error occurs while reading the input file or writing the output file.
+     * @throws org.xml.sax.SAXException If any parse error occurs.
+     * @throws com.dd.plist.PropertyListFormatException If the given property list has an invalid format.
+     * @throws java.text.ParseException If a date string could not be parsed.
      */
     public static void convertToXml(File in, File out) throws ParserConfigurationException, ParseException, SAXException, PropertyListFormatException, IOException {
         NSObject root = parse(in);
@@ -279,6 +312,12 @@ public static void saveAsBinary(NSObject root, OutputStream out) throws IOExcept
      *
      * @param in  The source file.
      * @param out The target file.
+     * @throws javax.xml.parsers.ParserConfigurationException If a document builder for parsing a XML property list
+     *                                                        could not be created. This should not occur.
+     * @throws java.io.IOException If any IO error occurs while reading the input file or writing the output file.
+     * @throws org.xml.sax.SAXException If any parse error occurs.
+     * @throws com.dd.plist.PropertyListFormatException If the given property list has an invalid format.
+     * @throws java.text.ParseException If a date string could not be parsed.
      */
     public static void convertToBinary(File in, File out) throws IOException, ParserConfigurationException, ParseException, SAXException, PropertyListFormatException {
         NSObject root = parse(in);
@@ -320,6 +359,12 @@ public static void saveAsASCII(NSArray root, File out) throws IOException {
      *
      * @param in  The source file.
      * @param out The target file.
+     * @throws javax.xml.parsers.ParserConfigurationException If a document builder for parsing a XML property list
+     *                                                        could not be created. This should not occur.
+     * @throws java.io.IOException If any IO error occurs while reading the input file or writing the output file.
+     * @throws org.xml.sax.SAXException If any parse error occurs.
+     * @throws com.dd.plist.PropertyListFormatException If the given property list has an invalid format.
+     * @throws java.text.ParseException If a date string could not be parsed.
      */
     public static void convertToASCII(File in, File out) throws ParserConfigurationException, ParseException, SAXException, PropertyListFormatException, IOException {
         NSObject root = parse(in);
@@ -374,6 +419,12 @@ public static void saveAsGnuStepASCII(NSArray root, File out) throws IOException
      *
      * @param in  The source file.
      * @param out The target file.
+     * @throws javax.xml.parsers.ParserConfigurationException If a document builder for parsing a XML property list
+     *                                                        could not be created. This should not occur.
+     * @throws java.io.IOException If any IO error occurs while reading the input file or writing the output file.
+     * @throws org.xml.sax.SAXException If any parse error occurs.
+     * @throws com.dd.plist.PropertyListFormatException If the given property list has an invalid format.
+     * @throws java.text.ParseException If a date string could not be parsed.
      */
     public static void convertToGnuStepASCII(File in, File out) throws ParserConfigurationException, ParseException, SAXException, PropertyListFormatException, IOException {
         NSObject root = parse(in);