Fixes JavaDoc issues highlighted in #1000; removes DataSerializable from ItemStack

octo-byte · Zidane · commit b201f148daf9 · 2016-10-15T23:57:38.000-05:00
DataHolder already extends DataSerializable.
diff --git a/src/main/java/org/spongepowered/api/command/args/GenericArguments.java b/src/main/java/org/spongepowered/api/command/args/GenericArguments.java
@@ -252,7 +252,7 @@ public static CommandFlags.Builder flags() {
     }
 
     /**
-     * Consumes a series of arguments. Usage is the elements concated
+     * Consumes a series of arguments. Usage is the elements concencated
      *
      * @param elements The series of arguments to expect
      * @return the element to match the input
@@ -1287,7 +1287,7 @@ private double parseRelativeDouble(CommandArgs args, String arg, @Nullable Doubl
             boolean relative = arg.startsWith("~");
             if (relative) {
                 if (relativeTo == null) {
-                    throw args.createError(t("Relative position specified but source does not have a postion"));
+                    throw args.createError(t("Relative position specified but source does not have a position"));
                 }
                 arg = arg.substring(1);
                 if (arg.isEmpty()) {
diff --git a/src/main/java/org/spongepowered/api/command/spec/CommandSpec.java b/src/main/java/org/spongepowered/api/command/spec/CommandSpec.java
@@ -334,7 +334,7 @@ public CommandExecutor getExecutor() {
     }
 
     /**
-     * Gets the active input tokenizer used for this commmand.
+     * Gets the active input tokenizer used for this command.
      *
      * @return This command's input tokenizer
      */
diff --git a/src/main/java/org/spongepowered/api/data/DataSerializable.java b/src/main/java/org/spongepowered/api/data/DataSerializable.java
@@ -29,7 +29,7 @@
 /**
  * Represents an object that can be represented by a {@link DataContainer}.
  * <p>DataContainers received from {@link DataSerializable#toContainer()}
- * should be considered to be copies of the original data, and therefor,
+ * should be considered to be copies of the original data, and therefore,
  * thread safe.</p>
  */
 public interface DataSerializable {
@@ -38,7 +38,7 @@ public interface DataSerializable {
      * Gets the content version of this {@link DataSerializable}. The version
      * may differ between instances of plugins and implementations such that
      * the {@link DataView} from {@link #toContainer()} may include different
-     * information, or remove other information as they are no longer deemend
+     * information, or remove other information as they are no longer deemed
      * necessary. The version goes hand in hand with {@link DataContentUpdater}
      * as it is required when there exists any {@link DataView} of this
      * {@link DataSerializable} with an "older" version.
diff --git a/src/main/java/org/spongepowered/api/data/key/Keys.java b/src/main/java/org/spongepowered/api/data/key/Keys.java
@@ -379,7 +379,6 @@ public final class Keys {
 
     public static final Key<Value<Fish>> FISH_TYPE = KeyFactory.fake("FISH_TYPE");
 
-    /**
     /**
      * Represents the {@link Key} for representing the
      * {@link FluidStackSnapshot} contained within an item container. Item
diff --git a/src/main/java/org/spongepowered/api/effect/potion/PotionEffectTypes.java b/src/main/java/org/spongepowered/api/effect/potion/PotionEffectTypes.java
@@ -27,7 +27,7 @@
 import org.spongepowered.api.util.generator.dummy.DummyObjectProvider;
 
 /**
- * An enumaration of all possible {@link PotionEffectType}s in vanilla minecraft.
+ * An enumeration of all possible {@link PotionEffectType}s in vanilla Minecraft.
  */
 public final class PotionEffectTypes {
 
diff --git a/src/main/java/org/spongepowered/api/event/server/query/QueryServerEvent.java b/src/main/java/org/spongepowered/api/event/server/query/QueryServerEvent.java
@@ -229,7 +229,7 @@ interface Full extends Basic {
          * Gets the map of custom keys and values to respond with.
          *
          * <p>If settings any of the keys or values causes the message
-         * to go oer the maximum size, the message will be automatically
+         * to go over the maximum size, the message will be automatically
          * truncated.</p>
          *
          * @return The map of custom keys and values to respond with
diff --git a/src/main/java/org/spongepowered/api/item/inventory/ItemStack.java b/src/main/java/org/spongepowered/api/item/inventory/ItemStack.java
@@ -33,7 +33,6 @@
 import org.spongepowered.api.block.BlockType;
 import org.spongepowered.api.block.tileentity.TileEntity;
 import org.spongepowered.api.data.DataHolder;
-import org.spongepowered.api.data.DataSerializable;
 import org.spongepowered.api.data.DataView;
 import org.spongepowered.api.data.key.Key;
 import org.spongepowered.api.data.manipulator.DataManipulator;
@@ -53,11 +52,11 @@
  * Represents a stack of a specific {@link ItemType}. Supports serialization and
  * can be compared using the comparators listed in {@link ItemStackComparators}.
  *
- * <p>{@link ItemStack}s have varying properties and data, it is adviseable to
- * use {@link DataHolder#get(Class)} to retrieve different information
- * regarding this item stack.</p>
+ * <p>{@link ItemStack}s have a variety of properties and data. It is advised to
+ * use {@link DataHolder#get(Class)} in order to retrieve information regarding
+ * this item stack.</p>
  */
-public interface ItemStack extends DataHolder, DataSerializable, Translatable {
+public interface ItemStack extends DataHolder, Translatable {
 
     /**
      * Creates a new {@link Builder} to build an {@link ItemStack}.
diff --git a/src/main/java/org/spongepowered/api/item/inventory/equipment/EquipmentTypes.java b/src/main/java/org/spongepowered/api/item/inventory/equipment/EquipmentTypes.java
@@ -34,7 +34,7 @@ public final class EquipmentTypes {
     // SORTFIELDS:ON
 
     /**
-     * Any type, all other types should sublass this to allow instanceof checks
+     * Any type, all other types should subclass this to allow instanceof checks
      * to succeed.
      */
     public static final EquipmentType ANY = DummyObjectProvider.createFor(EquipmentType.class, "ANY");
diff --git a/src/main/java/org/spongepowered/api/item/inventory/property/AcceptsItems.java b/src/main/java/org/spongepowered/api/item/inventory/property/AcceptsItems.java
@@ -82,7 +82,7 @@ public int compareTo(Property<?, ?> other) {
 
     /**
      * Returns true if <em>other</em> is also an {@link AcceptsItems} property
-     * and <b>any</b> item appearing in the other property's collecion appears
+     * and <b>any</b> item appearing in the other property's collection appears
      * in this property's collection. In formal terms, the method returns true
      * if the size of the intersection between the two item type collections is
      * greater than zero.
diff --git a/src/main/java/org/spongepowered/api/item/inventory/type/TileEntityInventory.java b/src/main/java/org/spongepowered/api/item/inventory/type/TileEntityInventory.java
@@ -38,7 +38,7 @@
  * at liberty to return the TE object directly but as far as consumers are
  * concerned the TE instance and the inventory are separate things.
  *
- * <p>This is intented to provide a consistent way of dealing with inventories
+ * <p>This is intended to provide a consistent way of dealing with inventories
  * regardless of the "owner" of the inventory. Thus, any code capable of dealing
  * with a {@link Carrier} is intrinsically able to deal with a TE inventory just
  * as they would with any Entity inventory or any other type of Carrier for that
diff --git a/src/main/java/org/spongepowered/api/network/ChannelBuf.java b/src/main/java/org/spongepowered/api/network/ChannelBuf.java
@@ -798,7 +798,7 @@ public interface ChannelBuf {
 
     /**
      * Sets the specified {@link DataView} at the current writerIndex and
-     * increases the writerIndex according to the lenght of the data view
+     * increases the writerIndex according to the length of the data view
      * in this buffer.
      *
      * @param data The data view data
diff --git a/src/main/java/org/spongepowered/api/service/permission/option/OptionSubjectData.java b/src/main/java/org/spongepowered/api/service/permission/option/OptionSubjectData.java
@@ -0,0 +1,74 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package org.spongepowered.api.service.permission.option;
+
+import org.spongepowered.api.service.context.Context;
+import org.spongepowered.api.service.permission.SubjectData;
+
+import java.util.Map;
+import java.util.Set;
+
+public interface OptionSubjectData extends SubjectData {
+
+    /**
+     * Return all options for all context combinations currently registered.
+     *
+     * @return An immutable snapshot of all options data
+     */
+    Map<Set<Context>, Map<String, String>> getAllOptions();
+
+    /**
+     * Get options for a specific context combination.
+     *
+     * @param contexts The context combination to get options for
+     * @return All available options, returning an empty map if none are present
+     */
+    Map<String, String> getOptions(Set<Context> contexts);
+
+    /**
+     * Set a specific option to a value.
+     *
+     * @param contexts The context combination to set the given option in
+     * @param key The key to set. Case-insensitive.
+     * @param value The value to set.
+     * @return Whether the operation was successful
+     */
+    boolean setOption(Set<Context> contexts, String key, String value);
+
+    /**
+     * Clear all options in the given context combination.
+     *
+     * @param contexts The context combination
+     * @return Whether the operation was successful (any options were removed)
+     */
+    boolean clearOptions(Set<Context> contexts);
+
+    /**
+     * Clear all options.
+     *
+     * @return Whether the operation was successful
+     */
+    boolean clearOptions();
+}
diff --git a/src/main/java/org/spongepowered/api/statistic/StatisticFormat.java b/src/main/java/org/spongepowered/api/statistic/StatisticFormat.java
@@ -37,7 +37,7 @@ public interface StatisticFormat extends CatalogType {
      * Formats the given value from the statistic to a human readable form.
      *
      * @param value The value to format
-     * @return The formated value
+     * @return The formatted value
      */
     String format(long value);
 
diff --git a/src/main/java/org/spongepowered/api/util/Direction.java b/src/main/java/org/spongepowered/api/util/Direction.java
@@ -286,7 +286,7 @@ public boolean isCardinal() {
 
     /**
      * Return true if the direction is of an ordinal direction (northwest,
-     * southwest, southeast, northeaast).
+     * southwest, southeast, northeast).
      *
      * @return True if ordinal
      */
diff --git a/src/main/java/org/spongepowered/api/world/ChunkTicketManager.java b/src/main/java/org/spongepowered/api/world/ChunkTicketManager.java
@@ -168,7 +168,7 @@ interface LoadingTicket {
          * Sets the number of chunks this ticket will load at once.
          *
          * @param numChunks The number of chunks this ticket can load at once
-         * @return True if sucessful, false if the number of chunks is above the
+         * @return True if successful, false if the number of chunks is above the
          *         maximum allowed for this ticket
          */
         boolean setNumChunks(int numChunks);
diff --git a/src/main/java/org/spongepowered/api/world/World.java b/src/main/java/org/spongepowered/api/world/World.java
@@ -28,6 +28,7 @@
 import com.flowpowered.math.vector.Vector3i;
 import org.spongepowered.api.Sponge;
 import org.spongepowered.api.effect.Viewer;
+import org.spongepowered.api.entity.Entity;
 import org.spongepowered.api.entity.living.player.Player;
 import org.spongepowered.api.event.cause.Cause;
 import org.spongepowered.api.service.context.ContextSource;
@@ -170,6 +171,19 @@ default Optional<Chunk> loadChunk(Vector3i chunkPosition, boolean shouldGenerate
      */
     Iterable<Chunk> getLoadedChunks();
 
+    /**
+     * Gets the entity whose {@link UUID} matches the provided id, possibly
+     * returning no entity if the entity is not loaded or non-existent.
+     *
+     * <p>For world implementations, only some parts of the world is usually
+     * loaded, so this method may return no entity if the entity is not
+     * loaded.</p>
+     *
+     * @param uuid The unique id
+     * @return An entity, if available
+     */
+    Optional<Entity> getEntity(UUID uuid);
+
     /**
      * Gets the world border for the world.
      *
diff --git a/src/main/java/org/spongepowered/api/world/gen/populator/Lake.java b/src/main/java/org/spongepowered/api/world/gen/populator/Lake.java
@@ -32,7 +32,7 @@
 
 /**
  * Represents a populator which will attempt to spawn lakes within the chunk
- * dependending on a random chance.
+ * depending on a random chance.
  */
 public interface Lake extends Populator {
 
diff --git a/src/main/java/org/spongepowered/api/world/storage/WorldStorage.java b/src/main/java/org/spongepowered/api/world/storage/WorldStorage.java
@@ -56,7 +56,7 @@ public interface WorldStorage {
      * exist in the world.
      *
      * <p>Note that this is an asynchronous check as the storage of chunks can
-     * not be guaranteed to remain in synch with the server, let alone on the
+     * not be guaranteed to remain in sync with the server, let alone on the
      * server thread.</p>
      *
      * <p>It is imperative to understand that the {@link CompletableFuture} task
@@ -74,7 +74,7 @@ public interface WorldStorage {
      *
      * <p>The container is a read only instance of the data, and therefor should
      * not be considered as mutable data. Changes are NOT saved, and the data
-     * may not be in synch with the server if the chunk is currently loaded.</p>
+     * may not be in sync with the server if the chunk is currently loaded.</p>
      *
      * <p>This may not return a {@link DataContainer} in the event there is no
      * chunk data generated at the desired coordinates.</p>

Original file line number	Diff line number	Diff line change
`@@ -252,7 +252,7 @@ public static CommandFlags.Builder flags() {`
`252`	`252`	`}`
`253`	`253`
`254`	`254`	`/**`
`255`		`- * Consumes a series of arguments. Usage is the elements concated`
	`255`	`+ * Consumes a series of arguments. Usage is the elements concencated`
`256`	`256`	`*`
`257`	`257`	`* @param elements The series of arguments to expect`
`258`	`258`	`* @return the element to match the input`
`@@ -1287,7 +1287,7 @@ private double parseRelativeDouble(CommandArgs args, String arg, @Nullable Doubl`
`1287`	`1287`	`boolean relative = arg.startsWith("~");`
`1288`	`1288`	`if (relative) {`
`1289`	`1289`	`if (relativeTo == null) {`
`1290`		`- throw args.createError(t("Relative position specified but source does not have a postion"));`
	`1290`	`+ throw args.createError(t("Relative position specified but source does not have a position"));`
`1291`	`1291`	`}`
`1292`	`1292`	`arg = arg.substring(1);`
`1293`	`1293`	`if (arg.isEmpty()) {`
Original file line number	Diff line number	Diff line change
`@@ -334,7 +334,7 @@ public CommandExecutor getExecutor() {`
`334`	`334`	`}`
`335`	`335`
`336`	`336`	`/**`
`337`		`- * Gets the active input tokenizer used for this commmand.`
	`337`	`+ * Gets the active input tokenizer used for this command.`
`338`	`338`	`*`
`339`	`339`	`* @return This command's input tokenizer`
`340`	`340`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -229,7 +229,7 @@ interface Full extends Basic {`
`229`	`229`	`* Gets the map of custom keys and values to respond with.`
`230`	`230`	`*`
`231`	`231`	`* <p>If settings any of the keys or values causes the message`
`232`		`- * to go oer the maximum size, the message will be automatically`
	`232`	`+ * to go over the maximum size, the message will be automatically`
`233`	`233`	`* truncated.</p>`
`234`	`234`	`*`
`235`	`235`	`* @return The map of custom keys and values to respond with`
Original file line number	Diff line number	Diff line change
`@@ -38,7 +38,7 @@`
`38`	`38`	`* at liberty to return the TE object directly but as far as consumers are`
`39`	`39`	`* concerned the TE instance and the inventory are separate things.`
`40`	`40`	`*`
`41`		`- * <p>This is intented to provide a consistent way of dealing with inventories`
	`41`	`+ * <p>This is intended to provide a consistent way of dealing with inventories`
`42`	`42`	`* regardless of the "owner" of the inventory. Thus, any code capable of dealing`
`43`	`43`	`* with a {@link Carrier} is intrinsically able to deal with a TE inventory just`
`44`	`44`	`* as they would with any Entity inventory or any other type of Carrier for that`