From 88ef4eb3c0aeffaaf8ab51a333f4aa8806b462b8 Mon Sep 17 00:00:00 2001 From: themode Date: Mon, 12 Oct 2020 03:18:02 +0200 Subject: [PATCH] Comments --- .../java/net/minestom/server/data/Data.java | 16 ++--- .../net/minestom/server/instance/Chunk.java | 58 +++++++++---------- .../server/instance/IChunkLoader.java | 10 ++-- .../server/storage/StorageLocation.java | 34 ++++++----- .../server/storage/StorageManager.java | 10 +++- .../server/timer/SchedulerManager.java | 45 ++++++++------ .../java/net/minestom/server/timer/Task.java | 10 ++-- .../minestom/server/timer/TaskBuilder.java | 19 +++--- .../net/minestom/server/timer/TaskStatus.java | 2 +- 9 files changed, 111 insertions(+), 93 deletions(-) diff --git a/src/main/java/net/minestom/server/data/Data.java b/src/main/java/net/minestom/server/data/Data.java index 806f01e12..33c68db0b 100644 --- a/src/main/java/net/minestom/server/data/Data.java +++ b/src/main/java/net/minestom/server/data/Data.java @@ -4,7 +4,7 @@ import java.util.Collections; import java.util.Set; /** - * Represent an object which contain key/value based data. + * Represents an object which contain key/value based data. *

* Please see {@link DataImpl} for the default implementation. */ @@ -47,7 +47,7 @@ public interface Data { }; /** - * Set a value to a specific key + * Set a value to a specific key. * * @param key the key * @param value the value object @@ -57,7 +57,7 @@ public interface Data { void set(String key, T value, Class type); /** - * Retrieve a value based on its key + * Retrieve a value based on its key. * * @param key the key * @param the value type @@ -66,7 +66,7 @@ public interface Data { T get(String key); /** - * Retrieve a value based on its key, give a default value if not found + * Retrieve a value based on its key, give a default value if not found. * * @param key the key * @param defaultValue the value to return if the key is not found @@ -76,7 +76,7 @@ public interface Data { T getOrDefault(String key, T defaultValue); /** - * Get if the data has a key + * Get if the data has a key. * * @param key the key to check * @return true if the data contains the key @@ -84,21 +84,21 @@ public interface Data { boolean hasKey(String key); /** - * Get the list of data keys + * Get the list of data keys. * * @return an unmodifiable {@link Set} containing all keys */ Set getKeys(); /** - * Get if the data is empty or not + * Get if the data is empty or not. * * @return true if the data does not contain anything, false otherwise */ boolean isEmpty(); /** - * Clone this data + * Clone this data. * * @return a cloned data object */ diff --git a/src/main/java/net/minestom/server/instance/Chunk.java b/src/main/java/net/minestom/server/instance/Chunk.java index 9fe09da91..bc1aa0c5f 100644 --- a/src/main/java/net/minestom/server/instance/Chunk.java +++ b/src/main/java/net/minestom/server/instance/Chunk.java @@ -91,20 +91,20 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Set a block at a position + * Set a block at a position. *

- * This is used when the previous block has to be destroyed, meaning that it clears the previous data and update method + * This is used when the previous block has to be destroyed, meaning that it clears the previous data and update method. *

* WARNING: this method is not thread-safe (in order to bring performance improvement with {@link ChunkBatch} & {@link BlockBatch}) * The thread-safe version is {@link InstanceContainer#setSeparateBlocks(int, int, int, short, short, Data)} (or any similar instance methods) - * Otherwise, you can simply do not forget to have this chunk synchronized when this is called + * Otherwise, you can simply do not forget to have this chunk synchronized when this is called. * * @param x the block X * @param y the block Y * @param z the block Z * @param blockStateId the block state id * @param customBlockId the custom block id - * @param data the data of the block, can be null + * @param data the {@link Data} of the block, can be null * @param updatable true if the block has an update method * Warning: customBlockId cannot be 0 and needs to be valid since the update delay and method * will be retrieved from the associated {@link CustomBlock} object @@ -112,19 +112,19 @@ public abstract class Chunk implements Viewable, DataContainer { public abstract void UNSAFE_setBlock(int x, int y, int z, short blockStateId, short customBlockId, Data data, boolean updatable); /** - * Execute a chunk tick + * Execute a chunk tick. *

- * Should be used to update all the blocks in the chunk + * Should be used to update all the blocks in the chunk. *

- * WARNING: this method doesn't necessary have to be thread-safe, proceed with caution + * WARNING: this method doesn't necessary have to be thread-safe, proceed with caution. * * @param time the time of the update in milliseconds - * @param instance the instance linked to this chunk + * @param instance the {@link Instance} linked to this chunk */ public abstract void tick(long time, Instance instance); /** - * Get the block state id at a position + * Get the block state id at a position. * * @param x the block X * @param y the block Y @@ -134,7 +134,7 @@ public abstract class Chunk implements Viewable, DataContainer { public abstract short getBlockStateId(int x, int y, int z); /** - * Get the custom block id at a position + * Get the custom block id at a position. * * @param x the block X * @param y the block Y @@ -144,7 +144,7 @@ public abstract class Chunk implements Viewable, DataContainer { public abstract short getCustomBlockId(int x, int y, int z); /** - * Change the block state id and the custom block id at a position + * Change the block state id and the custom block id at a position. * * @param x the block X * @param y the block Y @@ -155,7 +155,7 @@ public abstract class Chunk implements Viewable, DataContainer { protected abstract void refreshBlockValue(int x, int y, int z, short blockStateId, short customBlockId); /** - * Change the block state id at a position (the custom block id stays the same) + * Change the block state id at a position (the custom block id stays the same). * * @param x the block X * @param y the block Y @@ -165,7 +165,7 @@ public abstract class Chunk implements Viewable, DataContainer { protected abstract void refreshBlockStateId(int x, int y, int z, short blockStateId); /** - * Get the {@link Data} at a block index + * Get the {@link Data} at a block index. * * @param index the block index * @return the {@link Data} at the block index, null if none @@ -173,7 +173,7 @@ public abstract class Chunk implements Viewable, DataContainer { public abstract Data getBlockData(int index); /** - * Set the {@link Data} at a position + * Set the {@link Data} at a position. * * @param x the block X * @param y the block Y @@ -183,14 +183,14 @@ public abstract class Chunk implements Viewable, DataContainer { public abstract void setBlockData(int x, int y, int z, Data data); /** - * Get all the block entities in this chunk + * Get all the block entities in this chunk. * * @return the block entities in this chunk */ public abstract Set getBlockEntities(); /** - * Serialize the chunk into bytes + * Serialize the chunk into bytes. * * @return the serialized chunk, can be null if this chunk cannot be serialized * @see #readChunk(BinaryReader, ChunkCallback) which should be able to read what is written in this method @@ -198,9 +198,9 @@ public abstract class Chunk implements Viewable, DataContainer { public abstract byte[] getSerializedData(); /** - * Read the chunk from binary + * Read the chunk from binary. *

- * Used if the chunk is loaded from file + * Used if the chunk is loaded from file. * * @param reader the data reader * WARNING: the data will not necessary be read directly in the same thread, @@ -217,7 +217,7 @@ public abstract class Chunk implements Viewable, DataContainer { protected abstract ChunkDataPacket getFreshPacket(); /** - * Get the {@link CustomBlock} at a position + * Get the {@link CustomBlock} at a position. * * @param x the block X * @param y the block Y @@ -230,7 +230,7 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Get the {@link CustomBlock} at a block index + * Get the {@link CustomBlock} at a block index. * * @param index the block index * @return the {@link CustomBlock} at the block index @@ -247,7 +247,7 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Get the chunk X + * Get the chunk X. * * @return the chunk X */ @@ -256,7 +256,7 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Get the chunk Z + * Get the chunk Z. * * @return the chunk Z */ @@ -304,7 +304,7 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Retrieve (and save if needed) the updated data packet + * Retrieve (and save if needed) the updated data packet. * * @param consumer the consumer called once the packet is sure to be up-to-date */ @@ -323,7 +323,7 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Get a {@link ChunkDataPacket} which should contain the full chunk + * Get a {@link ChunkDataPacket} which should contain the full chunk. * * @return a fresh full chunk data packet */ @@ -334,7 +334,7 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Get a {@link ChunkDataPacket} which should contain the non-full chunk + * Get a {@link ChunkDataPacket} which should contain the non-full chunk. * * @return a fresh non-full chunk data packet */ @@ -345,7 +345,7 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Used to verify if the chunk should still be kept in memory + * Used to verify if the chunk should still be kept in memory. * * @return true if the chunk is loaded */ @@ -516,14 +516,14 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Set the chunk as "unloaded" + * Set the chunk as "unloaded". */ protected void unload() { this.loaded = false; } /** - * Get if a block state id represents a block entity + * Get if a block state id represents a block entity. * * @param blockStateId the block state id to check * @return true if {@code blockStateId} represents a block entity @@ -534,7 +534,7 @@ public abstract class Chunk implements Viewable, DataContainer { } /** - * Get the index of a position, used to store blocks + * Get the index of a position, used to store blocks. * * @param x the block X * @param y the block Y diff --git a/src/main/java/net/minestom/server/instance/IChunkLoader.java b/src/main/java/net/minestom/server/instance/IChunkLoader.java index 16008029c..3905a878e 100644 --- a/src/main/java/net/minestom/server/instance/IChunkLoader.java +++ b/src/main/java/net/minestom/server/instance/IChunkLoader.java @@ -11,11 +11,11 @@ public interface IChunkLoader { /** * Load a {@link Chunk}, all blocks should be set since the {@link ChunkGenerator} is not applied * - * @param instance the instance where the chunk belong + * @param instance the {@link Instance} where the {@link Chunk} belong * @param chunkX the chunk X * @param chunkZ the chunk Z - * @param callback the callback executed when the chunk is done loading, - * never called if something went wrong + * @param callback the callback executed when the {@link Chunk} is done loading, + * never called if the method returns false. * @return true if the chunk loaded successfully, false otherwise */ boolean loadChunk(Instance instance, int chunkX, int chunkZ, ChunkCallback callback); @@ -23,8 +23,8 @@ public interface IChunkLoader { /** * Save a {@link Chunk} with a callback for when it is done * - * @param chunk the chunk to save - * @param callback the callback executed when the chunk is done saving, + * @param chunk the {@link Chunk} to save + * @param callback the callback executed when the {@link Chunk} is done saving, * should be called even if the saving failed (you can throw an exception) */ void saveChunk(Chunk chunk, Runnable callback); diff --git a/src/main/java/net/minestom/server/storage/StorageLocation.java b/src/main/java/net/minestom/server/storage/StorageLocation.java index 52eb9c72b..bfc6f1c03 100644 --- a/src/main/java/net/minestom/server/storage/StorageLocation.java +++ b/src/main/java/net/minestom/server/storage/StorageLocation.java @@ -12,7 +12,8 @@ import java.util.Map; /** * Represent an area which contain data. *

- * Each {@link StorageLocation} has a {@link StorageSystem} associated to it which is used to save and retrieve data from keys. + * Each {@link StorageLocation} has a {@link StorageSystem} associated to it + * which is used to save and retrieve data from keys. */ public class StorageLocation { @@ -33,7 +34,7 @@ public class StorageLocation { } /** - * Get the data associated with a key using {@link StorageSystem#get(String)} + * Get the data associated with a key using {@link StorageSystem#get(String)}. * * @param key the key * @return the data associated to {@code key} @@ -44,7 +45,7 @@ public class StorageLocation { } /** - * Set a data associated to a key using {@link StorageSystem#set(String, byte[])} + * Set a data associated to a key using {@link StorageSystem#set(String, byte[])}. * * @param key the key of the data * @param data the data @@ -55,7 +56,7 @@ public class StorageLocation { } /** - * Delete a key using the associated {@link StorageSystem} + * Delete a key using the associated {@link StorageSystem}. * * @param key the key * @see StorageSystem#delete(String) @@ -65,7 +66,7 @@ public class StorageLocation { } /** - * Close the {@link StorageLocation} using {@link StorageSystem#close()} + * Close the {@link StorageLocation} using {@link StorageSystem#close()}. * * @see StorageSystem#close() */ @@ -74,10 +75,10 @@ public class StorageLocation { } /** - * Set an object associated to a key + * Set an object associated to a key. *

* It does use registered {@link DataType} located on {@link DataManager} - * So you need to register all the types that you use + * So you need to register all the types that you use. * * @param key the key * @param object the data object @@ -98,10 +99,10 @@ public class StorageLocation { } /** - * Retrieve a serialized object associated to a key + * Retrieve a serialized object associated to a key. *

- * It does use registered {@link DataType} located on {@link DataManager} - * So you need to register all the types that you use + * It does use registered {@link DataType} located on {@link DataManager}. + * So you need to register all the types that you use. * * @param key the key * @param type the class of the data @@ -128,7 +129,8 @@ public class StorageLocation { } /** - * Get an unique {@link SerializableData} which is cloned if cached or retrieved with the default {@link StorageSystem} + * Get an unique {@link SerializableData} + * which is cloned if cached or retrieved with the default {@link StorageSystem}. * * @param key the key of the data * @param dataContainer the {@link DataContainer} which will contain the new data @@ -178,7 +180,7 @@ public class StorageLocation { } /** - * Save a specified cached {@link SerializableData} and remove it from memory + * Save a specified cached {@link SerializableData} and remove it from memory. * * @param key the specified cached data key */ @@ -197,7 +199,7 @@ public class StorageLocation { } /** - * Save the all the cached {@link SerializableData} + * Save the all the cached {@link SerializableData}. */ public void saveCachedData() { synchronized (cachedData) { @@ -206,7 +208,7 @@ public class StorageLocation { } /** - * Save an unique cached {@link SerializableData} + * Save an unique cached {@link SerializableData}. * * @param key the data key */ @@ -218,9 +220,9 @@ public class StorageLocation { } /** - * Get the location of this storage + * Get the location of this storage. *

- * WARNING: this is not necessary a file or folder path + * WARNING: this is not necessary a file or folder path. * * @return the location */ diff --git a/src/main/java/net/minestom/server/storage/StorageManager.java b/src/main/java/net/minestom/server/storage/StorageManager.java index 9b0b448c0..fb9602723 100644 --- a/src/main/java/net/minestom/server/storage/StorageManager.java +++ b/src/main/java/net/minestom/server/storage/StorageManager.java @@ -10,6 +10,10 @@ import java.util.HashMap; import java.util.Map; import java.util.function.Supplier; +/** + * Manager used to retrieve {@link StorageLocation} with {@link #getLocation(String, StorageOptions, StorageSystem)} + * and define the default {@link StorageSystem} with {@link #defineDefaultStorageSystem(Supplier)}. + */ public final class StorageManager { private static final Logger LOGGER = LoggerFactory.getLogger(StorageManager.class); @@ -52,8 +56,8 @@ public final class StorageManager { } /** - * Used to get an access to the specified location - * The default {@link StorageSystem} provider will be used + * Used to get an access to the specified location. + * The default {@link StorageSystem} provider will be used. * * @param location the location * @return the {@link StorageLocation} at {@code location} with the default {@link StorageSystem} @@ -85,7 +89,7 @@ public final class StorageManager { } /** - * Get all locations which have been loaded by {@link #getLocation(String)} + * Get all the {@link StorageLocation} which have been loaded by {@link #getLocation(String)} * or {@link #getLocation(String, StorageOptions, StorageSystem)} * * @return an unmodifiable list of all the loaded {@link StorageLocation} diff --git a/src/main/java/net/minestom/server/timer/SchedulerManager.java b/src/main/java/net/minestom/server/timer/SchedulerManager.java index 6ab9dac91..133ef38f9 100644 --- a/src/main/java/net/minestom/server/timer/SchedulerManager.java +++ b/src/main/java/net/minestom/server/timer/SchedulerManager.java @@ -14,7 +14,14 @@ import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicInteger; /** - * An object which manages all the {@link Task}'s + * An object which manages all the {@link Task}'s. + *

+ * {@link Task} first need to be built with {@link #buildTask(Runnable)}, you can then specify a delay with as example + * {@link TaskBuilder#delay(long, net.minestom.server.utils.time.TimeUnit)} + * or {@link TaskBuilder#repeat(long, net.minestom.server.utils.time.TimeUnit)} + * and to finally schedule {@link TaskBuilder#schedule()}. + *

+ * Shutdown {@link Task} are built with {@link #buildShutdownTask(Runnable)}. */ public class SchedulerManager { @@ -51,38 +58,38 @@ public class SchedulerManager { } /** - * Initializes a new {@link TaskBuilder} for creating a task. + * Initializes a new {@link TaskBuilder} for creating a {@link Task}. * - * @param runnable The task to run when scheduled - * @return the task builder + * @param runnable The {@link Task} to run when scheduled + * @return the {@link TaskBuilder} */ public TaskBuilder buildTask(Runnable runnable) { return new TaskBuilder(this, runnable); } /** - * Initializes a new {@link TaskBuilder} for creating a shutdown task + * Initializes a new {@link TaskBuilder} for creating a shutdown {@link Task} * - * @param runnable The shutdown task to run when scheduled - * @return the task builder + * @param runnable The shutdown {@link Task} to run when scheduled + * @return the {@link TaskBuilder} */ public TaskBuilder buildShutdownTask(Runnable runnable) { return new TaskBuilder(this, runnable, true); } /** - * Removes/Forces the end of a task + * Removes/Forces the end of a {@link Task} * - * @param task The task to remove + * @param task The {@link Task} to remove */ public void removeTask(Task task) { this.tasks.remove(task.getId()); } /** - * Removes/Forces the end of a task + * Removes/Forces the end of a {@link Task} * - * @param task The task to remove + * @param task The {@link Task} to remove */ public void removeShutdownTask(Task task) { this.shutdownTasks.remove(task.getId()); @@ -124,36 +131,36 @@ public class SchedulerManager { } /** - * Gets a {@link Collection} with all registered tasks + * Gets a {@link Collection} with all the registered {@link Task} * - * @return a {@link Collection} with all registered tasks + * @return a {@link Collection} with all the registered {@link Task} */ public ObjectCollection getTasks() { return tasks.values(); } /** - * Gets a {@link Collection} with all registered shutdown tasks + * Gets a {@link Collection} with all the registered shutdown {@link Task} * - * @return a {@link Collection} with all registered shutdown tasks + * @return a {@link Collection} with all the registered shutdown {@link Task} */ public ObjectCollection getShutdownTasks() { return shutdownTasks.values(); } /** - * Gets the execution service for all registered tasks + * Gets the execution service for all the registered {@link Task} * - * @return the execution service for all registered tasks + * @return the execution service for all the registered {@link Task} */ public ExecutorService getBatchesPool() { return batchesPool; } /** - * Gets the scheduled execution service for all registered tasks + * Gets the scheduled execution service for all the registered {@link Task} * - * @return the scheduled execution service for all registered tasks + * @return the scheduled execution service for all the registered {@link Task} */ public ScheduledExecutorService getTimerExecutionService() { return timerExecutionService; diff --git a/src/main/java/net/minestom/server/timer/Task.java b/src/main/java/net/minestom/server/timer/Task.java index 964d38ffe..8e6d5d552 100644 --- a/src/main/java/net/minestom/server/timer/Task.java +++ b/src/main/java/net/minestom/server/timer/Task.java @@ -6,6 +6,8 @@ import java.util.concurrent.TimeUnit; /** * An Object that represents a task that is scheduled for execution on the application. + *

+ * Tasks are built in {@link SchedulerManager} and scheduled by a {@link TaskBuilder}. */ public class Task implements Runnable { @@ -30,10 +32,10 @@ public class Task implements Runnable { * Creates a task * * @param schedulerManager The manager for the task - * @param runnable The task to run when scheduled - * @param shutdown Defines whether the task is a shutdown task - * @param delay The time to delay - * @param repeat The time until the repetition + * @param runnable The task to run when scheduled + * @param shutdown Defines whether the task is a shutdown task + * @param delay The time to delay + * @param repeat The time until the repetition */ public Task(SchedulerManager schedulerManager, Runnable runnable, boolean shutdown, long delay, long repeat) { this.schedulerManager = schedulerManager; diff --git a/src/main/java/net/minestom/server/timer/TaskBuilder.java b/src/main/java/net/minestom/server/timer/TaskBuilder.java index 232d4886a..9b56a3dab 100644 --- a/src/main/java/net/minestom/server/timer/TaskBuilder.java +++ b/src/main/java/net/minestom/server/timer/TaskBuilder.java @@ -3,7 +3,10 @@ package net.minestom.server.timer; import net.minestom.server.utils.time.TimeUnit; /** - * A builder which represents a fluent Object to schedule tasks + * A builder which represents a fluent Object to schedule tasks. + *

+ * You can specify a delay with {@link #delay(long, TimeUnit)} or {@link #repeat(long, TimeUnit)} + * and then schedule the {@link Task} with {@link #schedule()}. */ public class TaskBuilder { @@ -44,7 +47,7 @@ public class TaskBuilder { } /** - * Specifies that the task should delay its execution by the specified amount of time. + * Specifies that the {@link Task} should delay its execution by the specified amount of time. * * @param time The time to delay * @param unit The unit of time for {@code time} @@ -56,10 +59,10 @@ public class TaskBuilder { } /** - * Specifies that the task should continue to run after waiting for the specified value until it is terminated. + * Specifies that the {@link Task} should continue to run after waiting for the specified value until it is terminated. * * @param time The time until the repetition - * @param unit The unit of time for {@code time} + * @param unit The {@link TimeUnit} for {@code time} * @return this builder, for chaining */ public TaskBuilder repeat(long time, TimeUnit unit) { @@ -68,7 +71,7 @@ public class TaskBuilder { } /** - * Clears the delay interval of the task + * Clears the delay interval of the {@link Task} * * @return this builder, for chaining */ @@ -78,7 +81,7 @@ public class TaskBuilder { } /** - * Clears the repeat interval of the task + * Clears the repeat interval of the {@link Task} * * @return this builder, for chaining */ @@ -88,9 +91,9 @@ public class TaskBuilder { } /** - * Schedule this task for execution + * Schedule this {@link Task} for execution * - * @return the built task + * @return the built {@link Task} */ public Task schedule() { Task task = new Task( diff --git a/src/main/java/net/minestom/server/timer/TaskStatus.java b/src/main/java/net/minestom/server/timer/TaskStatus.java index 25fe6bbdb..b1d726bb3 100644 --- a/src/main/java/net/minestom/server/timer/TaskStatus.java +++ b/src/main/java/net/minestom/server/timer/TaskStatus.java @@ -1,7 +1,7 @@ package net.minestom.server.timer; /** - * An enumeration that representing all available statuses for a task + * An enumeration that representing all available statuses for a {@link Task} */ public enum TaskStatus {