Documentation changes, no code changes.

Modified per feedback by Debajit
Some more typos fixed

7 files changed, 134 insertions, 73 deletions

diff --git a/src/com/google/wireless/gdata2/data/Entry.java b/src/com/google/wireless/gdata2/data/Entry.java
index 266ff29..a1a73a4 100644
--- a/src/com/google/wireless/gdata2/data/Entry.java
+++ b/src/com/google/wireless/gdata2/data/Entry.java
@@ -6,10 +6,16 @@ import com.google.wireless.gdata2.data.batch.BatchInfo;
 import com.google.wireless.gdata2.parser.ParseException;
 
 /**
- * Entry in a GData feed.
+ * Entry in a GData feed. This is the rough equivalent of the atom:Entry
+ * element. The "atom:entry" element represents an individual entry, 
+ * acting as a container for metadata and data associated with the 
+ * entry. This element can appear as a child of the atom:feed element, 
+ * or it can appear as the document (i.e., top-level) element of a 
+ * standalone Atom Entry Document.
+ * The Entry class serves as a base class for Google service specific subclasses,
+ * like a contact or a calendar event. As a base class it takes care of the default 
+ * attributes and elements that are common to all entries.
  */
-// allow for writing directly into data structures used by native PIM, etc.,
-// APIs.
 public class Entry {
     private String id = null;
     private String title = null;
diff --git a/src/com/google/wireless/gdata2/data/ExtendedProperty.java b/src/com/google/wireless/gdata2/data/ExtendedProperty.java
index 3f6d958..1e8d060 100644
--- a/src/com/google/wireless/gdata2/data/ExtendedProperty.java
+++ b/src/com/google/wireless/gdata2/data/ExtendedProperty.java
@@ -6,6 +6,11 @@ import com.google.wireless.gdata2.parser.ParseException;
 
 /**
  * The extendedProperty gdata type
+ * Allows you to store a limited amount of custom data as an auxiliary
+ * property of the enclosing entity. 
+ * Note that the presence of anyForeignElement allows feed to optionally 
+ * embed any valid XML within gd:extendedProperty element 
+ * (mutually exclusive with value attribute).
  */
 public class ExtendedProperty {
   private String name;
@@ -19,26 +24,54 @@ public class ExtendedProperty {
       this.xmlBlob = xmlBlob;
   }
 
+  /** 
+   * Returns the xml embedded inside the extended property 
+   * element 
+   * Mutually exclusive with the value property 
+   * @return the xml as a string 
+   */  
   public String getXmlBlob() {
     return xmlBlob;
   }
 
+  /** 
+   * Sets the embedded xml for the extended property element. 
+   * Mutually exclusive with the value property
+   * @param xmlBlob xml as a string
+   */
   public void setXmlBlob(String xmlBlob) {
     this.xmlBlob = xmlBlob;
   }
 
+  /**
+   * @return the name of the extended property expressed as a URI. Extended  
+   * property URIs usually follow the {scheme}#{local-name} convention. 
+   */
   public String getName() {
     return name;
   }
 
+  /**
+   * @param name set's the name of the extended property
+   */
   public void setName(String name) {
     this.name = name;
   }
 
+  /** 
+   * Returns the value attribute of the extended property 
+   * element.Mutually exclusive with the xmlBlob property 
+   * @return the value
+   */
   public String getValue() {
     return value;
   }
 
+  /** 
+   * Sets the value attribute of the extended property. Mutually
+   * exclusive with the xmlBlog property 
+   * @param value 
+   */
   public void setValue(String value) {
     this.value = value;
   }
diff --git a/src/com/google/wireless/gdata2/data/Feed.java b/src/com/google/wireless/gdata2/data/Feed.java
index 92d719a..76c9e8a 100644
--- a/src/com/google/wireless/gdata2/data/Feed.java
+++ b/src/com/google/wireless/gdata2/data/Feed.java
@@ -7,7 +7,6 @@ package com.google.wireless.gdata2.data;
  * not contain any of the entries in that feed -- the entries are yielded
  * separately from this Feed.
  */
-// TODO: comment that setters are only used for parsing code.
 public class Feed {
     private int totalResults;
     private int startIndex;
@@ -25,26 +24,53 @@ public class Feed {
     public Feed() {
     }
 
+    /** 
+     * The approximate number of total results in the feed 
+	 * @return totalResults
+	 */
     public int getTotalResults() {
         return totalResults;
     }
 
+    /** 
+    *  The number of toal results in the feed Only used during
+    *  parsing of the feed
+	 * @param totalResults 
+	 */
     public void setTotalResults(int totalResults) {
         this.totalResults = totalResults;
     }
 
+    /** 
+     * The starting Index of the current result set 
+	 * @return startIndex
+	 */
     public int getStartIndex() {
         return startIndex;
     }
 
+    /** 
+    *  The starting index of the current result set Only used during
+    *  parsing of the feed
+	 * @param startIndex 
+	 */
     public void setStartIndex(int startIndex) {
         this.startIndex = startIndex;
     }
 
+    /** 
+     * The number of items per Page in this result set 
+	 * @return itemsPerPage
+	 */
     public int getItemsPerPage() {
         return itemsPerPage;
     }
 
+    /** 
+    *  The number of items per page in this result set
+    *  Only used during parsing of the feed
+	 * @param itemsPerPage 
+	 */
     public void setItemsPerPage(int itemsPerPage) {
         this.itemsPerPage = itemsPerPage;
     }
@@ -56,8 +82,10 @@ public class Feed {
         return category;
     }
 
-    /**
-     * @param category the category to set
+    /** 
+     * The category to set 
+     * Only used during parsing of the feed 
+     * @param category 
      */
     public void setCategory(String category) {
         this.category = category;
@@ -70,8 +98,10 @@ public class Feed {
         return categoryScheme;
     }
 
-    /**
-     * @param categoryScheme the categoryScheme to set
+    /** 
+     * The categoryScheme to set 
+     * Only used during parsing of the feed
+     * @param categoryScheme 
      */
     public void setCategoryScheme(String categoryScheme) {
         this.categoryScheme = categoryScheme;
@@ -84,8 +114,10 @@ public class Feed {
         return id;
     }
 
-    /**
-     * @param id the id to set
+    /** 
+     * the id to set 
+     * Only used during parsing of the feed 
+     * @param id 
      */
     public void setId(String id) {
         this.id = id;
@@ -98,8 +130,10 @@ public class Feed {
         return lastUpdated;
     }
 
-    /**
-     * @param lastUpdated the lastUpdated to set
+    /** 
+     * The lastUpdated to set 
+     * Only used during parsing of the feed 
+     * @param lastUpdated 
      */
     public void setLastUpdated(String lastUpdated) {
         this.lastUpdated = lastUpdated;
@@ -112,8 +146,10 @@ public class Feed {
         return title;
     }
 
-    /**
-     * @param title the title to set
+    /** 
+     * the title to set 
+     * Only used during parsing of the feed 
+     * @param title 
      */
     public void setTitle(String title) {
         this.title = title;
diff --git a/src/com/google/wireless/gdata2/data/StringUtils.java b/src/com/google/wireless/gdata2/data/StringUtils.java
index 40181c4..5cefb83 100644
--- a/src/com/google/wireless/gdata2/data/StringUtils.java
+++ b/src/com/google/wireless/gdata2/data/StringUtils.java
@@ -41,6 +41,14 @@ public final class StringUtils {
         return true;
     }
 
+    /** 
+     * Converts a string into an integer. Uses the default value 
+     * passed in if the string can not be converted 
+     * @param string The String that should be converted to an integer
+     * @param defaultValue The default value that should be used if 
+     *        the string is not convertable
+     * @return the integer value of the string or the default value
+     */
     public static int parseInt(String string, int defaultValue) {
         if (string != null) {
             try {
@@ -52,8 +60,15 @@ public final class StringUtils {
         return defaultValue;
     }
 
+    /** 
+     * Tests if a character is a whitespace character 
+     * Uses 
+     * http://en.wikipedia.org/wiki/Whitespace_%28computer_science%29 
+     * as the algorithm. 
+     * @param c A character to be tested. 
+     * @return true if the character is a whitespace 
+	 */
     public static boolean isWhitespace(char c) {
-    // Reference: http://en.wikipedia.org/wiki/Whitespace_%28computer_science%29
         return ('\u0009' <= c && c <= '\r') || c == '\u0020' || c == '\u0085'
             || c == '\u00A0' || c == '\u1680' || c == '\u180E'
             || ('\u2000' <= c && c <= '\u200A') || c == '\u2028' || c == '\u2029'
diff --git a/src/com/google/wireless/gdata2/data/XmlUtils.java b/src/com/google/wireless/gdata2/data/XmlUtils.java
index 5224e47..a69d817 100644
--- a/src/com/google/wireless/gdata2/data/XmlUtils.java
+++ b/src/com/google/wireless/gdata2/data/XmlUtils.java
@@ -36,6 +36,17 @@ public final class XmlUtils {
         return parser.getText();
     }
 
+    /**
+     * Extracts the child text for the first child element in the pull parser.
+     * Other child elements will be discarded
+     * @param parser The XmlPullParser parsing an XML document. 
+     * @return The child text for the first child element.  May be null, if there
+     * is no child text.
+     * @throws XmlPullParserException Thrown if the child text could not be
+     * parsed.
+     * @throws IOException Thrown if the InputStream behind the parser cannot
+     * be read.
+     */
     public static String extractFirstChildTextIgnoreRest(XmlPullParser parser)
             throws XmlPullParserException, IOException {
         int parentDepth = parser.getDepth();
@@ -57,6 +68,16 @@ public final class XmlUtils {
                 + "depth " + parentDepth);
     }
 
+    /**
+     * Returns the nextDirectChildTag
+     * @param parser The XmlPullParser parsing an XML document. 
+     * @param parentDepth the depth in the hierachy of the parent node
+     * @return The child element 
+     * @throws XmlPullParserException Thrown if the child text could not be
+     * parsed.
+     * @throws IOException Thrown if the InputStream behind the parser cannot
+     * be read.
+     */
     public static String nextDirectChildTag(XmlPullParser parser, int parentDepth)
             throws XmlPullParserException, IOException {
         int targetDepth = parentDepth + 1;
@@ -76,58 +97,4 @@ public final class XmlUtils {
         throw new XmlPullParserException("End of document reached; never saw expected end tag at "
                 + "depth " + parentDepth);
     }
-
-//    public static void parseChildrenToSerializer(XmlPullParser parser, XmlSerializer serializer)
-//            throws XmlPullParserException, IOException {
-//        int parentDepth = parser.getDepth();
-//        int eventType = parser.getEventType();
-//        while (eventType != XmlPullParser.END_DOCUMENT) {
-//            // TODO: call parser.nextToken(), so we get all entities, comments, whitespace, etc.?
-//            // find out if this is necessary.
-//            eventType = parser.next();
-//            int depth = parser.getDepth();
-//            String name;
-//            String ns;
-//            switch (eventType) {
-//                case XmlPullParser.START_TAG:
-//                    name = parser.getName();
-//                    ns = parser.getNamespace();
-//                    // grab all of the namespace definitions between the previous depth and the
-//                    // current depth (e.g., what was just defined in the start tag).
-//                    int nstackBegin = parser.getNamespaceCount(depth - 1);
-//                    int nstackEnd = parser.getNamespaceCount(depth);
-//                    for (int i = nstackBegin; i < nstackEnd; ++i) {
-//                        serializer.setPrefix(parser.getNamespacePrefix(i),
-//                                parser.getNamespaceUri(i));
-//                    }
-//                    serializer.startTag(ns, name);
-//
-//                    int numAttrs = parser.getAttributeCount();
-//                    for (int i = 0; i < numAttrs; ++i) {
-//                        String attrNs = parser.getAttributeNamespace(i);
-//                        String attrName = parser.getAttributeName(i);
-//                        String attrValue = parser.getAttributeValue(i);
-//                        serializer.attribute(attrNs, attrName, attrValue);
-//                    }
-//                    break;
-//                case XmlPullParser.END_TAG:
-//                    if (depth == parentDepth) {
-//                        // we're done.
-//                        return;
-//                    }
-//                    name = parser.getName();
-//                    ns = parser.getNamespace();
-//                    serializer.endTag(ns, name);
-//                    break;
-//                case XmlPullParser.TEXT:
-//                    serializer.text(parser.getText());
-//                    break;
-//                default:
-//                    // ignore the rest.
-//                    break;
-//            }
-//        }
-//        throw new XmlPullParserException("End of document reached; never saw expected end tag "
-//            + "at depth " + parentDepth);
-//    }
 }
diff --git a/src/com/google/wireless/gdata2/serializer/GDataSerializer.java b/src/com/google/wireless/gdata2/serializer/GDataSerializer.java
index f818984..587790d 100644
--- a/src/com/google/wireless/gdata2/serializer/GDataSerializer.java
+++ b/src/com/google/wireless/gdata2/serializer/GDataSerializer.java
@@ -8,13 +8,11 @@ import java.io.IOException;
 import java.io.OutputStream;
 
 /**
- * Interface for serializing GData entries.
+ * Interface for serializing GData entries. A serializer has to be aware 
+ * what mode it is in while it is serializing.
  */
 public interface GDataSerializer {
 
-    // TODO: I hope the three formats does not bite us.  Each serializer has
-    // to pay attention to what "mode" it is in when serializing.
-    
     /**
      * Serialize all data in the entry.  Used for debugging.
      */
diff --git a/src/com/google/wireless/gdata2/serializer/xml/XmlBatchGDataSerializer.java b/src/com/google/wireless/gdata2/serializer/xml/XmlBatchGDataSerializer.java
index a26dfd7..22a6824 100644
--- a/src/com/google/wireless/gdata2/serializer/xml/XmlBatchGDataSerializer.java
+++ b/src/com/google/wireless/gdata2/serializer/xml/XmlBatchGDataSerializer.java
@@ -41,6 +41,9 @@ public class XmlBatchGDataSerializer implements GDataSerializer {
     this.batch = batch;
   }
 
+  /* (non-Javadoc)
+  * @see GDataSerializer#getContentType()
+  */
   public String getContentType() {
     return "application/atom+xml";
   }
@@ -53,6 +56,9 @@ public class XmlBatchGDataSerializer implements GDataSerializer {
   }
 
 
+  /* (non-Javadoc)
+   * @see GDataSerializer#serialize()
+   */
   public void serialize(OutputStream out, int format)
       throws IOException, ParseException {
     XmlSerializer serializer;