From 4439983aceea7cd9592f64254cc749a0be6503be Mon Sep 17 00:00:00 2001 From: James Seibel Date: Sat, 26 Aug 2023 17:32:39 -0500 Subject: [PATCH] Fix some api:javadoc warnings and suppress future ones I don't like suppressing warnings, but in this case they want the javadocs to be a bit more verbose then necessary. --- api/build.gradle | 10 +++++++++ .../events/IDhApiEventInjector.java | 3 +++ .../override/IDhApiOverrideable.java | 4 +++- .../AbstractDhApiChunkWorldGenerator.java | 12 +++++++---- .../worldGenerator/IDhApiWorldGenerator.java | 21 +++++++++++++------ .../DependencyInjection/ApiEventInjector.java | 9 ++++++++ .../IDependencyInjector.java | 2 +- .../IOverrideInjector.java | 4 ++-- 8 files changed, 51 insertions(+), 14 deletions(-) diff --git a/api/build.gradle b/api/build.gradle index cb3195792..9172e5bf8 100644 --- a/api/build.gradle +++ b/api/build.gradle @@ -77,3 +77,13 @@ task addSourcesToCompiledJar(type: ShadowJar) { } } + +javadoc { + options { + // Don't log warnings. + // There are a lot of warnings related to missing @param and @return javadocs + // that aren't necessary and would clutter up said javadocs. + // For more info see: https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html + addStringOption('Xdoclint:all,-missing', '-quiet') + } +} diff --git a/api/src/main/java/com/seibel/distanthorizons/api/interfaces/events/IDhApiEventInjector.java b/api/src/main/java/com/seibel/distanthorizons/api/interfaces/events/IDhApiEventInjector.java index 79cdd31c0..9be0d8559 100644 --- a/api/src/main/java/com/seibel/distanthorizons/api/interfaces/events/IDhApiEventInjector.java +++ b/api/src/main/java/com/seibel/distanthorizons/api/interfaces/events/IDhApiEventInjector.java @@ -35,6 +35,8 @@ public interface IDhApiEventInjector extends IDependencyInjector /** * Unlinks the given event handler, preventing the handler from being called in the future. * + * @param dependencyInterface the base interface for the {@link IDhApiEvent} + * @param dependencyClassToRemove the concrete {@link IDhApiEvent} class to remove * @return true if the handler was unbound, false if the handler wasn't bound. * @throws IllegalArgumentException if the implementation object doesn't implement the interface */ @@ -48,6 +50,7 @@ public interface IDhApiEventInjector extends IDependencyInjector * @param abstractEvent event type * @param eventParameterObject event parameter * @param the parameter type taken by the event handlers. + * @param the {@link IDhApiEvent}'s class * @return if any of bound event handlers returned that this event should be canceled. */ > boolean fireAllEvents(Class abstractEvent, T eventParameterObject); diff --git a/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/IDhApiOverrideable.java b/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/IDhApiOverrideable.java index 1736e52d7..493ceaada 100644 --- a/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/IDhApiOverrideable.java +++ b/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/IDhApiOverrideable.java @@ -13,8 +13,10 @@ import com.seibel.distanthorizons.coreapi.interfaces.dependencyInjection.IOverri public interface IDhApiOverrideable extends IBindable { /** - * Higher (larger numerical) priorities override lower (smaller numerical) priorities .
+ * Higher (larger numerical) priorities override lower (smaller numerical) priorities.
* For most developers this can be left at the default. + * + * @return The priority of this interface, the lowest legal value is {@link IOverrideInjector#MIN_NON_CORE_OVERRIDE_PRIORITY}. */ default int getPriority() { return IOverrideInjector.DEFAULT_NON_CORE_OVERRIDE_PRIORITY; } diff --git a/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/worldGenerator/AbstractDhApiChunkWorldGenerator.java b/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/worldGenerator/AbstractDhApiChunkWorldGenerator.java index 2698c2d06..32892ae9e 100644 --- a/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/worldGenerator/AbstractDhApiChunkWorldGenerator.java +++ b/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/worldGenerator/AbstractDhApiChunkWorldGenerator.java @@ -61,10 +61,14 @@ public abstract class AbstractDhApiChunkWorldGenerator implements Closeable, IDh /** * This method is called to generate terrain over a given area * from a thread defined by Distant Horizons.

- * - * See {@link IDhApiWorldGenerator#generateChunks(int, int, byte, byte, EDhApiDistantGeneratorMode, ExecutorService, Consumer) IDhApiWorldGenerator.generateChunks} - * for the list of Object's this method should return along with additional documentation. - * + * + * @param chunkPosX the chunk X position in the level (not to be confused with the chunk's BlockPos in the level) + * @param chunkPosZ the chunk Z position in the level (not to be confused with the chunk's BlockPos in the level) + * @param generatorMode how far into the world gen pipeline this method run. See {@link EDhApiDistantGeneratorMode} for additional documentation. + * + * @return See {@link IDhApiWorldGenerator#generateChunks(int, int, byte, byte, EDhApiDistantGeneratorMode, ExecutorService, Consumer) IDhApiWorldGenerator.generateChunks} + * for the list of Object's this method should return along with additional documentation. + * * @see IDhApiWorldGenerator#generateChunks(int, int, byte, byte, EDhApiDistantGeneratorMode, ExecutorService, Consumer) IDhApiWorldGenerator#generateChunks */ public abstract Object[] generateChunk(int chunkPosX, int chunkPosZ, EDhApiDistantGeneratorMode generatorMode); diff --git a/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/worldGenerator/IDhApiWorldGenerator.java b/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/worldGenerator/IDhApiWorldGenerator.java index 8396ff340..3c412e96b 100644 --- a/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/worldGenerator/IDhApiWorldGenerator.java +++ b/api/src/main/java/com/seibel/distanthorizons/api/interfaces/override/worldGenerator/IDhApiWorldGenerator.java @@ -28,7 +28,7 @@ public interface IDhApiWorldGenerator extends Closeable, IDhApiOverrideable * * TODO: System currently only supports 1x1 block per data. * - * @see EDhApiDetailLevel + * @see EDhApiDetailLevel */ default byte getSmallestDataDetailLevel() { return EDhApiDetailLevel.BLOCK.detailLevel; } /** @@ -37,7 +37,7 @@ public interface IDhApiWorldGenerator extends Closeable, IDhApiOverrideable * Default detail level is 0
* For more information on what detail levels represent see: {@link EDhApiDetailLevel}. * - * @see EDhApiDetailLevel + * @see EDhApiDetailLevel */ default byte getLargestDataDetailLevel() { return EDhApiDetailLevel.BLOCK.detailLevel; } @@ -49,7 +49,7 @@ public interface IDhApiWorldGenerator extends Closeable, IDhApiOverrideable * Default detail level is 4
* For more information on what detail levels represent see: {@link EDhApiDetailLevel}. * - * @see EDhApiDetailLevel + * @see EDhApiDetailLevel */ default byte getMinGenerationGranularity() { return EDhApiDetailLevel.CHUNK.detailLevel; } @@ -61,11 +61,11 @@ public interface IDhApiWorldGenerator extends Closeable, IDhApiOverrideable * Default detail level is 6 (4x4 chunks)
* For more information on what detail levels represent see: {@link EDhApiDetailLevel}. * - * @see EDhApiDetailLevel + * @see EDhApiDetailLevel */ default byte getMaxGenerationGranularity() { return (byte) (EDhApiDetailLevel.CHUNK.detailLevel + 2); } - /** Returns true if the generator is unable to accept new generation requests. */ + /** @return true if the generator is unable to accept new generation requests. */ boolean isBusy(); @@ -81,13 +81,22 @@ public interface IDhApiWorldGenerator extends Closeable, IDhApiOverrideable * After a chunk has been generated it (and any necessary supporting objects as listed below) should be passed into the * resultConsumer's {@link Consumer#accept} method. If the Consumer is given the wrong data * type(s) it will disable the world generator and log an error with a list of objects it was expecting.
- * Note: these objects are minecraft version dependent and will change without notice! + * Note: these objects are minecraft version dependent and will change without notice! * Please run your generator in game at least once to confirm the objects you are returning are correct.

* * Consumer expected inputs for each minecraft version (in order):
* 1.16, 1.17, 1.18, 1.19, 1.20:
* - [net.minecraft.world.level.chunk.ChunkAccess]
* - [net.minecraft.world.level.ServerLevel] or [net.minecraft.world.level.ClientLevel]
+ * + * @param chunkPosMinX the chunk X position closest to negative infinity + * @param chunkPosMinZ the chunk Z position closest to negative infinity + * @param granularity TODO find a central location to store the definition of granularity. For now it is stored in the Core method: WorldGenerationQueue#startGenerationEvent + * @param targetDataDetail the LOD Detail level requested to generate. See {@link EDhApiDetailLevel} for additional information. + * @param generatorMode how far into the world gen pipeline this method run. See {@link EDhApiDistantGeneratorMode} for additional documentation. + * @param worldGeneratorThreadPool the thread pool that should be used when generating the returned {@link CompletableFuture}. + * @param resultConsumer the consumer that should be fired whenever a chunk finishes generating. + * @return a future that should run on the worldGeneratorThreadPool and complete once the given generation task has completed. */ CompletableFuture generateChunks( int chunkPosMinX, int chunkPosMinZ, diff --git a/api/src/main/java/com/seibel/distanthorizons/coreapi/DependencyInjection/ApiEventInjector.java b/api/src/main/java/com/seibel/distanthorizons/coreapi/DependencyInjection/ApiEventInjector.java index 36325d085..e268c7c2d 100644 --- a/api/src/main/java/com/seibel/distanthorizons/coreapi/DependencyInjection/ApiEventInjector.java +++ b/api/src/main/java/com/seibel/distanthorizons/coreapi/DependencyInjection/ApiEventInjector.java @@ -172,6 +172,15 @@ public class ApiEventInjector extends DependencyInjector implements } + /** + * Wraps the event parameter object in a {@link DhApiCancelableEventParam} or {@link DhApiEventParam} depending on + * if it should allow cancellation or not. + * + * @param event the event instance + * @param parameter the event's parameter object + * @param the event parameter type + * @return the event parameter wrapped in a {@link DhApiCancelableEventParam} or {@link DhApiEventParam} + */ public static DhApiEventParam createEventParamWrapper(IDhApiEvent event, T parameter) { return (event instanceof IDhApiCancelableEvent) ? new DhApiCancelableEventParam<>(parameter) : new DhApiEventParam<>(parameter); diff --git a/api/src/main/java/com/seibel/distanthorizons/coreapi/interfaces/dependencyInjection/IDependencyInjector.java b/api/src/main/java/com/seibel/distanthorizons/coreapi/interfaces/dependencyInjection/IDependencyInjector.java index 266c43e66..3024405b1 100644 --- a/api/src/main/java/com/seibel/distanthorizons/coreapi/interfaces/dependencyInjection/IDependencyInjector.java +++ b/api/src/main/java/com/seibel/distanthorizons/coreapi/interfaces/dependencyInjection/IDependencyInjector.java @@ -25,7 +25,7 @@ public interface IDependencyInjector /** - * This does not return incomplete dependencies.
+ * Does not return incomplete dependencies.
* See {@link #get(Class, boolean) get(Class, boolean)} for full documentation. * * @see #get(Class, boolean) diff --git a/api/src/main/java/com/seibel/distanthorizons/coreapi/interfaces/dependencyInjection/IOverrideInjector.java b/api/src/main/java/com/seibel/distanthorizons/coreapi/interfaces/dependencyInjection/IOverrideInjector.java index 15f9dcbc4..bf1d3d6ce 100644 --- a/api/src/main/java/com/seibel/distanthorizons/coreapi/interfaces/dependencyInjection/IOverrideInjector.java +++ b/api/src/main/java/com/seibel/distanthorizons/coreapi/interfaces/dependencyInjection/IOverrideInjector.java @@ -7,12 +7,12 @@ public interface IOverrideInjector { /** * All core overrides should have this priority.
- * Should be lower than MIN_OVERRIDE_PRIORITY. + * Should be lower than {@link IOverrideInjector#MIN_NON_CORE_OVERRIDE_PRIORITY}. */ public static final int CORE_PRIORITY = -1; /** * The lowest priority non-core overrides can have. - * Should be higher than CORE_PRIORITY. + * Should be higher than {@link IOverrideInjector#CORE_PRIORITY}. */ public static final int MIN_NON_CORE_OVERRIDE_PRIORITY = 0; /** The priority given to overrides that don't explicitly define a priority. */