Pulling all pending Bukkit-JavaDoc changes

src/main/java/org/bukkit/BanEntry.java

@@ -3,95 +3,125 @@
 import java.util.Date;
 
 /**
- * A single entry from the ban list. This may represent either a player ban or an
- * IP ban.<br />
+ * A single entry from a ban list. This may represent either a player ban or
+ * an IP ban.
+ * <p>
  * Ban entries include the following properties:
- * <ul>
- *     <li><b>Target Name/IP Address</b> - The target name or IP address
- *     <li><b>Creation Date</b> - The creation date of the ban
- *     <li><b>Source</b> - The source of the ban, such as a player, console, plugin, etc
- *     <li><b>Expiration Date</b> - The expiration date of the ban
- *     <li><b>Reason</b> - The reason for the ban
- * </ul>
- * Unsaved information is not automatically written to the implementation's ban list, instead,
- * the {@link #save()} method must be called to write the changes to the ban list. If this ban
- * entry has expired (such as from an unban) and is no longer found in the list, the {@link #save()}
- * call will re-add it to the list, therefore banning the victim specified.
+ * <table border=1>
+ * <tr>
+ *     <th>Property</th>
+ *     <th>Description</th>
+ * </tr><tr>
+ *     <td>Target Name / IP Address</td>
+ *     <td>The target name or IP address</td>
+ * </tr><tr>
+ *     <td>Creation Date</td>
+ *     <td>The creation date of the ban</td>
+ * </tr><tr>
+ *     <td>Source</td>
+ *     <td>The source of the ban, such as a player, console, plugin, etc</td>
+ * </tr><tr>
+ *     <td>Expiration Date</td>
+ *     <td>The expiration date of the ban</td>
+ * </tr><tr>
+ *     <td>Reason</td>
+ *     <td>The reason for the ban</td>
+ * </tr>
+ * </table>
+ * <p>
+ * Unsaved information is not automatically written to the implementation's
+ * ban list, instead, the {@link #save()} method must be called to write the
+ * changes to the ban list. If this ban entry has expired (such as from an
+ * unban) and is no longer found in the list, the {@link #save()} call will
+ * re-add it to the list, therefore banning the victim specified.
+ * <p>
+ * Likewise, changes to the associated {@link BanList} or other entries may or
+ * may not be reflected in this entry.
  */
 public interface BanEntry {
+
     /**
-     * Gets the target involved. This may be in the form of an IP or a player name.
+     * Gets the target involved. This may be in the form of an IP or a player
+     * name.
      *
-     * @return The target name or IP address
+     * @return the target name or IP address
      */
     public String getTarget();
 
     /**
      * Gets the date this ban entry was created.
      *
-     * @return The creation date
+     * @return the creation date
      */
     public Date getCreated();
 
     /**
-     * Sets the date this ban entry was created.<br />
-     * Use {@link #save()} to save the changes.
+     * Sets the date this ban entry was created.
      *
-     * @param created The new created date, cannot be null
+     * @param created the new created date, cannot be null
+     * @see #save() saving changes
      */
     public void setCreated(Date created);
 
     /**
-     * Gets the source of this ban.<br />
-     * A source is considered any String, although this is generally a player name.
+     * Gets the source of this ban.
+     * <p>
+     * Note: A source is considered any String, although this is generally a
+     * player name.
      *
-     * @return The source of the ban
+     * @return the source of the ban
      */
     public String getSource();
 
     /**
-     * Sets the source of this ban.<br />
-     * A source is considered any String, although this is generally a player name.<br />
-     * Use {@link #save()} to save the changes.
+     * Sets the source of this ban.
+     * <p>
+     * Note: A source is considered any String, although this is generally a
+     * player name.
      *
-     * @param source The new source where null values become empty strings
+     * @param source the new source where null values become empty strings
+     * @see #save() saving changes
      */
     public void setSource(String source);
 
     /**
      * Gets the date this ban expires on, or null for no defined end date.
      *
-     * @return The expiration date
+     * @return the expiration date
      */
     public Date getExpiration();
 
     /**
-     * Sets the date this ban expires on. Null values are considered "infinite" bans.<br />
-     * Use {@link #save()} to save the changes.
+     * Sets the date this ban expires on. Null values are considered
+     * "infinite" bans.
      *
-     * @param expiry The new expiration date, or null to indicate an eternity
+     * @param expiration the new expiration date, or null to indicate an
+     *     eternity
+     * @see #save() saving changes
      */
     public void setExpiration(Date expiration);
 
     /**
      * Gets the reason for this ban.
      *
-     * @return The ban reason or null if not set
+     * @return the ban reason, or null if not set
      */
     public String getReason();
 
     /**
-     * Sets the reason for this ban. Reasons must not be null.<br />
-     * Use {@link #save()} to save the changes.
+     * Sets the reason for this ban. Reasons must not be null.
      *
-     * @param reason The new reason, null values assume the implementation default
+     * @param reason the new reason, null values assume the implementation
+     *     default
+     * @see #save() saving changes
      */
     public void setReason(String reason);
 
     /**
-     * Saves the ban entry, overwriting any previous data in the ban list.<br />
-     * Saving the ban entry of an unbanned player will cause the player to be banned once again.
+     * Saves the ban entry, overwriting any previous data in the ban list.
+     * <p>
+     * Saving the ban entry of an unbanned player will cause the player to be
+     * banned once again.
      */
     public void save();
-
 }

src/main/java/org/bukkit/BanList.java

@@ -4,63 +4,69 @@
 import java.util.Set;
 
 /**
- * A ban list, containing bans of type {@link org.bukkit.BanList.Type}
+ * A ban list, containing bans of some {@link Type}.
  */
 public interface BanList {
+
+    /**
+     * Represents a ban-type that a {@link BanList} may track.
+     */
+    public enum Type {
+        /**
+         * Banned player names
+         */
+        NAME,
+        /**
+         * Banned player IP addresses
+         */
+        IP,
+        ;
+    }
+
     /**
      * Gets a {@link BanEntry} by target.
      *
-     * @param target Entry parameter to search for
-     * @return BanEntry for the submitted query, or null if none found
+     * @param target entry parameter to search for
+     * @return the corresponding entry, or null if none found
      */
     public BanEntry getBanEntry(String target);
 
     /**
-     * Adds a ban to the ban list. If a previous ban exists, this will overwrite the previous
-     * entry.
+     * Adds a ban to the this list. If a previous ban exists, this will
+     * update the previous entry.
      *
-     * @param target The target of the ban
-     * @param reason Reason for the ban. If null, the implementation default is assumed
-     * @param expires Expiration Date of the ban. If null, "infinity" is assumed
-     * @param source Source of the ban. If null, the implementation default is assumed
-     * @return The BanEntry of the added ban
+     * @param target the target of the ban
+     * @param reason reason for the ban, null indicates implementation default
+     * @param expires date for the ban's expiration (unban), or null to imply
+     *     forever
+     * @param source source of the ban, null indicates implementation default
+     * @return the entry for the newly created ban, or the entry for the
+     *     (updated) previous ban
      */
     public BanEntry addBan(String target, String reason, Date expires, String source);
 
     /**
-     * Gets a set containing every {@link BanEntry} in the BanList.
+     * Gets a set containing every {@link BanEntry} in this list.
      *
-     * @return an immutable set containing every BanEntry tracked by the BanList
+     * @return an immutable set containing every entry tracked by this list
      */
     public Set<BanEntry> getBanEntries();
 
     /**
-     * Gets if a {@link BanEntry} exists for the target, indicating ban status
+     * Gets if a {@link BanEntry} exists for the target, indicating an active
+     * ban status.
      *
-     * @param target Entry target to lookup
-     * @return true if a {@link BanEntry} exists for the name, indicating ban status
+     * @param target the target to find
+     * @return true if a {@link BanEntry} exists for the name, indicating an
+     *     active ban status, false otherwise
      */
     public boolean isBanned(String target);
 
     /**
-     * Removes the specified target from the list, therefore indicating a "not banned" status.
+     * Removes the specified target from this list, therefore indicating a
+     * "not banned" status.
      *
-     * @param target The target to remove from the list
+     * @param target the target to remove from this list
      */
     public void pardon(String target);
-
-    /**
-     * Represents the various types a {@link BanList} may track.
-     */
-    public enum Type {
-        /**
-         * Banned player names
-         */
-        NAME,
-        /**
-         * Banned player IP addresses
-         */
-        IP;
-    }
-
 }

src/main/java/org/bukkit/Bukkit.java

@@ -451,7 +451,7 @@ public static Set<OfflinePlayer> getBannedPlayers() {
      * @see Server#getBanList(BanList.Type)
      */
     public static BanList getBanList(BanList.Type type){
-    	return server.getBanList(type);
+        return server.getBanList(type);
     }
 
     /**

src/main/java/org/bukkit/Material.java

@@ -59,7 +59,7 @@
 import com.google.common.collect.Maps;
 
 /**
- * An enum of all material ids accepted by the official server + client
+ * An enum of all material IDs accepted by the official server and client
  */
 public enum Material {
     AIR(0, 0),

src/main/java/org/bukkit/OfflinePlayer.java

@@ -1,5 +1,7 @@
 package org.bukkit;
 
+import java.util.Date;
+
 import org.bukkit.configuration.serialization.ConfigurationSerializable;
 import org.bukkit.entity.AnimalTamer;
 import org.bukkit.entity.Player;
@@ -32,7 +34,9 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * Bans or unbans this player
      *
      * @param banned true if banned
-     * @deprecated Use {@link org.bukkit.BanList#addBan(String, String, java.util.Date, String)} or {@link org.bukkit.BanList#unban(String)} to enhance functionality
+     * @deprecated Use {@link org.bukkit.BanList#addBan(String, String, Date,
+     *     String)} or {@link org.bukkit.BanList#pardon(String)} to enhance
+     *     functionality
      */
     @Deprecated
     public void setBanned(boolean banned);