Improved comments.

git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@1801 b35dd754-fafc-0310-a699-88a17e54d16e

source/org/jivesoftware/smack/PacketCollector.java

@@ -123,7 +123,7 @@ public class PacketCollector {
     }
 
     /**
-     * Polls to see if a result is currently available and returns it, or
+     * Polls to see if a packet is currently available and returns it, or
      * immediately returns <tt>null</tt> if no packets are currently in the
      * result queue.
      *
@@ -139,6 +139,12 @@ public class PacketCollector {
         }
     }
 
+    /**
+     * Returns the next available packet. The method call will block (not return)
+     * until a packet is available.
+     *
+     * @return the next available packet.
+     */
     public synchronized Packet nextResult() {
         // Wait indefinitely until there is a result to return.
         while (resultQueue.isEmpty()) {
@@ -150,6 +156,14 @@ public class PacketCollector {
         return (Packet)resultQueue.removeLast();
     }
 
+    /**
+     * Returns the next available packet. The method call will block (not return)
+     * until a packet is available or the <tt>timeout</tt> has elapased. If the
+     * timeout elapses without a result, <tt>null</tt> will be returned.
+     *
+     * @param timeout the amount of time to wait for the next packet (in milleseconds).
+     * @return the next available packet.
+     */
     public synchronized Packet nextResult(long timeout) {
         // Wait up to the specified amount of time for a result.
         if (resultQueue.isEmpty()) {

source/org/jivesoftware/smack/packet/Presence.java

@@ -55,8 +55,22 @@ package org.jivesoftware.smack.packet;
 import org.jivesoftware.smack.*;
 
 /**
- * Represents XMPP presence packets. Every presence packet has a type, while a
- * number of attributes are optional:
+ * Represents XMPP presence packets. Every presence packet has a type, which is one of
+ * the following values:
+ * <ul>
+ *      <li><tt>Presence.Type.AVAILABLE</tt> -- (Default) indicates the user is available to
+ *          receive messages.
+ *      <li><tt>Presence.Type.UNAVAILABLE</tt> -- the user is unavailable to receive messages.
+ *      <li><tt>Presence.Type.SUBSCRIBE</tt> -- request subscription to recipient's presence.
+ *      <li><tt>Presence.Type.SUBSCRIBED</tt> -- grant subscription to sender's presence.
+ *      <li><tt>Presence.Type.UNSUBSCRIBE</tt> -- request removal of subscription to sender's
+ *          presence.
+ *      <li><tt>Presence.Type.UNSUBSCRIBED</tt> -- grant removal of subscription to sender's
+ *          presence.
+ *      <li><tt>Presence.Type.ERROR</tt> -- the presence packet contains an error message.
+ * </ul><p>
+ *
+ * A number of attributes are optional:
  * <ul>
  *      <li>Status -- free-form text describing a user's presence (i.e., gone to lunch).
  *      <li>Priority -- non-negative numerical priority of a sender's resource. The
@@ -64,7 +78,7 @@ import org.jivesoftware.smack.*;
  *          to a particular resource.
  *      <li>Mode -- one of four presence modes: chat, away, xa (extended away, and
  *          dnd (do not disturb).
- * </ul>
+ * </ul><p>
  *
  * Presence packets are used for two purposes. First, to notify the server of our
  * the clients current presence status. Second, they are used to subscribe and
@@ -104,10 +118,20 @@ public class Presence extends Packet {
         this.mode = mode;
     }
 
+    /**
+     * Returns the type of this presence packet.
+     *
+     * @return the type of the presence packet.
+     */
     public Type getType() {
         return type;
     }
 
+    /**
+     * Sets the type of the presence packet.
+     *
+     * @param type the type of the presence packet.
+     */
     public void setType(Type type) {
         this.type = type;
     }
@@ -181,7 +205,10 @@ public class Presence extends Packet {
         if (getFrom() != null) {
             buf.append("from=\"").append(getFrom()).append("\" ");
         }
-        buf.append("type=\"").append(type).append("\">");
+        if (type != Type.AVAILABLE) {
+            buf.append("type=\"").append(type).append("\"");
+        }
+        buf.append(">");
         if (status != null) {
             buf.append("<status>").append(status).append("</status>");
         }
@@ -206,6 +233,7 @@ public class Presence extends Packet {
         public static final Type SUBSCRIBED = new Type("subscribed");
         public static final Type UNSUBSCRIBE = new Type("unsubscribe");
         public static final Type UNSUBSCRIBED = new Type("unsubscribed");
+        public static final Type ERROR = new Type("error");
 
         private String value;
 
@@ -221,10 +249,7 @@ public class Presence extends Packet {
          * Returns the type constant associated with the String value.
          */
         public static Type fromString(String value) {
-            if ("available".equals(value)) {
-                return AVAILABLE;
-            }
-            else if ("unavailable".equals(value)) {
+            if ("unavailable".equals(value)) {
                 return UNAVAILABLE;
             }
             else if ("subscribe".equals(value)) {
@@ -239,6 +264,9 @@ public class Presence extends Packet {
             else if ("unsubscribed".equals(value)) {
                 return UNSUBSCRIBED;
             }
+            else if ("error".equals(value)) {
+                return ERROR;
+            }
             // Default to available.
             else {
                 return AVAILABLE;