twin/paper-mc
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-08-20 06:43:49 -07:00
Code Issues Packages Projects Releases Wiki Activity

Pulling all pending Bukkit-JavaDoc changes

Browse Source 
A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>
This commit is contained in:
Bukkit/Spigot
2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
paper-api/src/main/java/org/bukkit/permissions/Permissible.java
View File

@@ -9,7 +9,8 @@ import org.bukkit.plugin.Plugin;
public interface Permissible extends ServerOperator {
/**
* Checks if this object contains an override for the specified permission, by fully qualified name
* Checks if this object contains an override for the specified
* permission, by fully qualified name
*
* @param name Name of the permission
* @return true if the permission is set, otherwise false
@@ -17,7 +18,8 @@ public interface Permissible extends ServerOperator {
public boolean isPermissionSet(String name);
/**
* Checks if this object contains an override for the specified {@link Permission}
* Checks if this object contains an override for the specified {@link
* Permission}
*
* @param perm Permission to check
* @return true if the permission is set, otherwise false
@@ -27,7 +29,8 @@ public interface Permissible extends ServerOperator {
/**
* Gets the value of the specified permission, if set.
* <p>
* If a permission override is not set on this object, the default value of the permission will be returned.
* If a permission override is not set on this object, the default value
* of the permission will be returned.
*
* @param name Name of the permission
* @return Value of the permission
@@ -37,7 +40,8 @@ public interface Permissible extends ServerOperator {
/**
* Gets the value of the specified permission, if set.
* <p>
* If a permission override is not set on this object, the default value of the permission will be returned
* If a permission override is not set on this object, the default value
* of the permission will be returned
*
* @param perm Permission to get
* @return Value of the permission
@@ -45,9 +49,11 @@ public interface Permissible extends ServerOperator {
public boolean hasPermission(Permission perm);
/**
* Adds a new {@link PermissionAttachment} with a single permission by name and value
* Adds a new {@link PermissionAttachment} with a single permission by
* name and value
*
* @param plugin Plugin responsible for this attachment, may not be null or disabled
* @param plugin Plugin responsible for this attachment, may not be null
* or disabled
* @param name Name of the permission to attach
* @param value Value of the permission
* @return The PermissionAttachment that was just created
@@ -57,27 +63,34 @@ public interface Permissible extends ServerOperator {
/**
* Adds a new empty {@link PermissionAttachment} to this object
*
* @param plugin Plugin responsible for this attachment, may not be null or disabled
* @param plugin Plugin responsible for this attachment, may not be null
* or disabled
* @return The PermissionAttachment that was just created
*/
public PermissionAttachment addAttachment(Plugin plugin);
/**
* Temporarily adds a new {@link PermissionAttachment} with a single permission by name and value
* Temporarily adds a new {@link PermissionAttachment} with a single
* permission by name and value
*
* @param plugin Plugin responsible for this attachment, may not be null or disabled
* @param plugin Plugin responsible for this attachment, may not be null
* or disabled
* @param name Name of the permission to attach
* @param value Value of the permission
* @param ticks Amount of ticks to automatically remove this attachment after
* @param ticks Amount of ticks to automatically remove this attachment
* after
* @return The PermissionAttachment that was just created
*/
public PermissionAttachment addAttachment(Plugin plugin, String name, boolean value, int ticks);
/**
* Temporarily adds a new empty {@link PermissionAttachment} to this object
* Temporarily adds a new empty {@link PermissionAttachment} to this
* object
*
* @param plugin Plugin responsible for this attachment, may not be null or disabled
* @param ticks Amount of ticks to automatically remove this attachment after
* @param plugin Plugin responsible for this attachment, may not be null
* or disabled
* @param ticks Amount of ticks to automatically remove this attachment
* after
* @return The PermissionAttachment that was just created
*/
public PermissionAttachment addAttachment(Plugin plugin, int ticks);
@@ -86,19 +99,22 @@ public interface Permissible extends ServerOperator {
* Removes the given {@link PermissionAttachment} from this object
*
* @param attachment Attachment to remove
* @throws IllegalArgumentException Thrown when the specified attachment isn't part of this object
* @throws IllegalArgumentException Thrown when the specified attachment
* isn't part of this object
*/
public void removeAttachment(PermissionAttachment attachment);
/**
* Recalculates the permissions for this object, if the attachments have changed values.
* Recalculates the permissions for this object, if the attachments have
* changed values.
* <p>
* This should very rarely need to be called from a plugin.
*/
public void recalculatePermissions();
/**
* Gets a set containing all of the permissions currently in effect by this object
* Gets a set containing all of the permissions currently in effect by
* this object
*
* @return Set of currently effective permissions
*/

65
paper-api/src/main/java/org/bukkit/permissions/Permission.java
View File

@@ -12,7 +12,8 @@ import org.bukkit.Bukkit;
import org.bukkit.plugin.PluginManager;
/**
* Represents a unique permission that may be attached to a {@link Permissible}
* Represents a unique permission that may be attached to a {@link
* Permissible}
*/
public class Permission {
public static final PermissionDefault DEFAULT_PERMISSION = PermissionDefault.OP;
@@ -77,7 +78,8 @@ public class Permission {
/**
* Gets the children of this permission.
* <p>
* If you change this map in any form, you must call {@link #recalculatePermissibles()} to recalculate all {@link Permissible}s
* If you change this map in any form, you must call {@link
* #recalculatePermissibles()} to recalculate all {@link Permissible}s
*
* @return Permission children
*/
@@ -97,8 +99,10 @@ public class Permission {
/**
* Sets the default value of this permission.
* <p>
* This will not be saved to disk, and is a temporary operation until the server reloads permissions.
* Changing this default will cause all {@link Permissible}s that contain this permission to recalculate their permissions
* This will not be saved to disk, and is a temporary operation until the
* server reloads permissions. Changing this default will cause all {@link
* Permissible}s that contain this permission to recalculate their
* permissions
*
* @param value The new default to set
*/
@@ -123,7 +127,8 @@ public class Permission {
/**
* Sets the description of this permission.
* <p>
* This will not be saved to disk, and is a temporary operation until the server reloads permissions.
* This will not be saved to disk, and is a temporary operation until the
* server reloads permissions.
*
* @param value The new description to set
*/
@@ -136,7 +141,8 @@ public class Permission {
}
/**
* Gets a set containing every {@link Permissible} that has this permission.
* Gets a set containing every {@link Permissible} that has this
* permission.
* <p>
* This set cannot be modified.
*
@@ -149,7 +155,8 @@ public class Permission {
/**
* Recalculates all {@link Permissible}s that contain this permission.
* <p>
* This should be called after modifying the children, and is automatically called after modifying the default value
* This should be called after modifying the children, and is
* automatically called after modifying the default value
*/
public void recalculatePermissibles() {
Set<Permissible> perms = getPermissibles();
@@ -164,7 +171,8 @@ public class Permission {
/**
* Adds this permission to the specified parent permission.
* <p>
* If the parent permission does not exist, it will be created and registered.
* If the parent permission does not exist, it will be created and
* registered.
*
* @param name Name of the parent permission
* @param value The value to set this permission to
@@ -198,12 +206,18 @@ public class Permission {
}
/**
* Loads a list of Permissions from a map of data, usually used from retrieval from a yaml file.
* Loads a list of Permissions from a map of data, usually used from
* retrieval from a yaml file.
* <p>
* The data may contain a list of name:data, where the data contains the following keys:
* default: Boolean true or false. If not specified, false.
* children: Map<String, Boolean> of child permissions. If not specified, empty list.
* description: Short string containing a very small description of this description. If not specified, empty string.
* The data may contain a list of name:data, where the data contains the
* following keys:
* <ul>
* <li>default: Boolean true or false. If not specified, false.
* <li>children: Map<String, Boolean> of child permissions. If not
* specified, empty list.
* <li>description: Short string containing a very small description of
* this description. If not specified, empty string.
* </ul>
*
* @param data Map of permissions
* @param error An error message to show if a permission is invalid.
@@ -225,12 +239,16 @@ public class Permission {
}
/**
* Loads a Permission from a map of data, usually used from retrieval from a yaml file.
* Loads a Permission from a map of data, usually used from retrieval from
* a yaml file.
* <p>
* The data may contain the following keys:
* default: Boolean true or false. If not specified, false.
* children: Map<String, Boolean> of child permissions. If not specified, empty list.
* description: Short string containing a very small description of this description. If not specified, empty string.
* <ul>
* <li>default: Boolean true or false. If not specified, false.
* <li>children: Map<String, Boolean> of child permissions. If not
* specified, empty list.
* <li>description: Short string containing a very small description of
* this description. If not specified, empty string.
*
* @param name Name of the permission
* @param data Map of keys
@@ -241,12 +259,17 @@ public class Permission {
}
/**
* Loads a Permission from a map of data, usually used from retrieval from a yaml file.
* Loads a Permission from a map of data, usually used from retrieval from
* a yaml file.
* <p>
* The data may contain the following keys:
* default: Boolean true or false. If not specified, false.
* children: Map<String, Boolean> of child permissions. If not specified, empty list.
* description: Short string containing a very small description of this description. If not specified, empty string.
* <ul>
* <li>default: Boolean true or false. If not specified, false.
* <li>children: Map<String, Boolean> of child permissions. If not
* specified, empty list.
* <li>description: Short string containing a very small description of
* this description. If not specified, empty string.
* </ul>
*
* @param name Name of the permission
* @param data Map of keys

24
paper-api/src/main/java/org/bukkit/permissions/PermissionAttachment.java
View File

@@ -5,7 +5,8 @@ import java.util.Map;
import org.bukkit.plugin.Plugin;
/**
* Holds information about a permission attachment on a {@link Permissible} object
* Holds information about a permission attachment on a {@link Permissible}
* object
*/
public class PermissionAttachment {
private PermissionRemovedExecutor removed;
@@ -34,7 +35,8 @@ public class PermissionAttachment {
}
/**
* Sets an object to be called for when this attachment is removed from a {@link Permissible}. May be null.
* Sets an object to be called for when this attachment is removed from a
* {@link Permissible}. May be null.
*
* @param ex Object to be called when this is removed
*/
@@ -43,7 +45,8 @@ public class PermissionAttachment {
}
/**
* Gets the class that was previously set to be called when this attachment was removed from a {@link Permissible}. May be null.
* Gets the class that was previously set to be called when this
* attachment was removed from a {@link Permissible}. May be null.
*
* @return Object to be called when this is removed
*/
@@ -61,9 +64,11 @@ public class PermissionAttachment {
}
/**
* Gets a copy of all set permissions and values contained within this attachment.
* Gets a copy of all set permissions and values contained within this
* attachment.
* <p>
* This map may be modified but will not affect the attachment, as it is a copy.
* This map may be modified but will not affect the attachment, as it is a
* copy.
*
* @return Copy of all permissions and values expressed by this attachment
*/
@@ -95,7 +100,8 @@ public class PermissionAttachment {
/**
* Removes the specified permission from this attachment.
* <p>
* If the permission does not exist in this attachment, nothing will happen.
* If the permission does not exist in this attachment, nothing will
* happen.
*
* @param name Name of the permission to remove
*/
@@ -107,7 +113,8 @@ public class PermissionAttachment {
/**
* Removes the specified permission from this attachment.
* <p>
* If the permission does not exist in this attachment, nothing will happen.
* If the permission does not exist in this attachment, nothing will
* happen.
*
* @param perm Permission to remove
*/
@@ -118,7 +125,8 @@ public class PermissionAttachment {
/**
* Removes this attachment from its registered {@link Permissible}
*
* @return true if the permissible was removed successfully, false if it did not exist
* @return true if the permissible was removed successfully, false if it
* did not exist
*/
public boolean remove() {
try {

7
paper-api/src/main/java/org/bukkit/permissions/PermissionAttachmentInfo.java
View File

@@ -1,7 +1,8 @@
package org.bukkit.permissions;
/**
* Holds information on a permission and which {@link PermissionAttachment} provides it
* Holds information on a permission and which {@link PermissionAttachment}
* provides it
*/
public class PermissionAttachmentInfo {
private final Permissible permissible;
@@ -41,8 +42,8 @@ public class PermissionAttachmentInfo {
}
/**
* Gets the attachment providing this permission. This may be null for default
* permissions (usually parent permissions).
* Gets the attachment providing this permission. This may be null for
* default permissions (usually parent permissions).
*
* @return Attachment
*/

3
paper-api/src/main/java/org/bukkit/permissions/PermissionDefault.java
View File

@@ -20,7 +20,8 @@ public enum PermissionDefault {
}
/**
* Calculates the value of this PermissionDefault for the given operator value
* Calculates the value of this PermissionDefault for the given operator
* value
*
* @param op If the target is op
* @return True if the default should be true, or false

6
paper-api/src/main/java/org/bukkit/permissions/PermissionRemovedExecutor.java
View File

@@ -1,12 +1,14 @@
package org.bukkit.permissions;
/**
* Represents a class which is to be notified when a {@link PermissionAttachment} is removed from a {@link Permissible}
* Represents a class which is to be notified when a {@link
* PermissionAttachment} is removed from a {@link Permissible}
*/
public interface PermissionRemovedExecutor {
/**
* Called when a {@link PermissionAttachment} is removed from a {@link Permissible}
* Called when a {@link PermissionAttachment} is removed from a {@link
* Permissible}
*
* @param attachment Attachment which was removed
*/

3
paper-api/src/main/java/org/bukkit/permissions/ServerOperator.java
View File

@@ -3,7 +3,8 @@ package org.bukkit.permissions;
import org.bukkit.entity.Player;
/**
* Represents an object that may become a server operator, such as a {@link Player}
* Represents an object that may become a server operator, such as a {@link
* Player}
*/
public interface ServerOperator {