1 files changed, 36 insertions, 16 deletions
diff --git a/third_party/java/dd_plist/java/com/dd/plist/XMLPropertyListParser.java b/third_party/java/dd_plist/java/com/dd/plist/XMLPropertyListParser.java
index 14776ea0b8..6fcb7f9315 100644
--- a/third_party/java/dd_plist/java/com/dd/plist/XMLPropertyListParser.java
+++ b/third_party/java/dd_plist/java/com/dd/plist/XMLPropertyListParser.java
@@ -55,8 +55,8 @@ public class XMLPropertyListParser {
     private static DocumentBuilderFactory docBuilderFactory = null;
 
     /**
-     * Initialize the document builder factory so that it can be reuused and does not need to
-     * be reinitialized for each new parsing.
+     * Initialize the document builder factory so that it can be reused and does not need to
+     * be reinitialized for each parse action.
      */
     private static synchronized void initDocBuilderFactory() {
         docBuilderFactory = DocumentBuilderFactory.newInstance();
@@ -69,6 +69,8 @@ public class XMLPropertyListParser {
      * As DocumentBuilders are not thread-safe a new DocBuilder is generated for each request.
      *
      * @return A new DocBuilder that can parse property lists w/o an internet connection.
+     * @throws javax.xml.parsers.ParserConfigurationException If a document builder for parsing a XML property list
+     *                                                        could not be created. This should not occur.
      */
     private static synchronized DocumentBuilder getDocBuilder() throws ParserConfigurationException {
         if (docBuilderFactory == null)
@@ -92,24 +94,34 @@ public class XMLPropertyListParser {
      * Parses a XML property list file.
      *
      * @param f The XML 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.
      * @see javax.xml.parsers.DocumentBuilder#parse(java.io.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 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 ParseException, IOException, PropertyListFormatException, SAXException, ParserConfigurationException {
+    public static NSObject parse(File f) throws ParserConfigurationException, IOException, SAXException, PropertyListFormatException, ParseException {
         DocumentBuilder docBuilder = getDocBuilder();
 
         Document doc = docBuilder.parse(f);
 
-        return parseDocument(doc);
+        return parse(doc);
     }
 
     /**
      * Parses a XML property list from a byte array.
      *
      * @param bytes The byte array containing 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 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(final byte[] bytes) throws ParserConfigurationException, ParseException, SAXException, PropertyListFormatException, IOException {
         ByteArrayInputStream bis = new ByteArrayInputStream(bytes);
@@ -120,26 +132,33 @@ public class XMLPropertyListParser {
      * Parses a XML property list from an input stream.
      *
      * @param is The input stream pointing 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.
      * @see javax.xml.parsers.DocumentBuilder#parse(java.io.InputStream)
+     * @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(InputStream is) throws ParserConfigurationException, IOException, SAXException, PropertyListFormatException, ParseException {
         DocumentBuilder docBuilder = getDocBuilder();
 
         Document doc = docBuilder.parse(is);
 
-        return parseDocument(doc);
+        return parse(doc);
     }
 
     /**
-     * Parses the XML document by generating the appropriate NSObjects for each XML node.
+     * Parses a property list from an XML document.
      *
      * @param doc The XML document.
      * @return The root NSObject of the property list contained in the XML document.
-     * @throws Exception If an error occured during parsing.
+     * @throws java.io.IOException If any IO error occurs while reading the file.
+     * @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.
      */
-    private static NSObject parseDocument(Document doc) throws PropertyListFormatException, IOException, ParseException {
+    public static NSObject parse(Document doc) throws PropertyListFormatException, IOException, ParseException {
         DocumentType docType = doc.getDoctype();
         if (docType == null) {
             if (!doc.getDocumentElement().getNodeName().equals("plist")) {
@@ -174,7 +193,8 @@ public class XMLPropertyListParser {
      *
      * @param n The XML node.
      * @return The corresponding NSObject.
-     * @throws Exception If an error occured during parsing the node.
+     * @throws java.io.IOException If any IO error occurs while parsing a Base64 encoded NSData object.
+     * @throws java.text.ParseException If a date string could not be parsed.
      */
     private static NSObject parseObject(Node n) throws ParseException, IOException {
         String type = n.getNodeName();
@@ -219,7 +239,7 @@ public class XMLPropertyListParser {
      * Returns all element nodes that are contained in a list of nodes.
      *
      * @param list The list of nodes to search.
-     * @return The sublist containing only nodes representing actual elements.
+     * @return The sub-list containing only nodes representing actual elements.
      */
     private static List<Node> filterElementNodes(NodeList list) {
         List<Node> result = new ArrayList<Node>(list.getLength());