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.
2023-08-26 17:32:39 -05:00
parent 0978f4a4d8
commit 4439983ace
8 changed files with 51 additions and 14 deletions
@@ -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')
+    }
+}
@@ -35,6 +35,8 @@ public interface IDhApiEventInjector extends IDependencyInjector<IDhApiEvent>
 	/**
 	 * 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<IDhApiEvent>
 	 * @param abstractEvent event type
 	 * @param eventParameterObject event parameter
 	 * @param <T> the parameter type taken by the event handlers.
+	 * @param <U> the {@link IDhApiEvent}'s class
 	 * @return if any of bound event handlers returned that this event should be canceled.
 	 */
 	<T, U extends IDhApiEvent<T>> boolean fireAllEvents(Class<U> abstractEvent, T eventParameterObject);
@@ -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 . <br>
+	 * Higher (larger numerical) priorities override lower (smaller numerical) priorities. <br>
 	 * 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; }
 	
@@ -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. <br><br>
-	 *
-	 * 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);
@@ -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 <br>
 	 * 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 <br>
 	 * 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) <br>
 	 * 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. <br>
-	 * <strong>Note:</strong> these objects are minecraft version dependent and will change without notice!
+	 * <strong>Note:</strong> these objects are minecraft version dependent and <i>will</i> change without notice!
 	 * Please run your generator in game at least once to confirm the objects you are returning are correct. <br><br>
 	 *
 	 * Consumer expected inputs for each minecraft version (in order): <br>
 	 * <strong>1.16</strong>, <strong>1.17</strong>, <strong>1.18</strong>, <strong>1.19</strong>, <strong>1.20</strong>: <br>
 	 *  - [net.minecraft.world.level.chunk.ChunkAccess] <br>
 	 *  - [net.minecraft.world.level.ServerLevel] or [net.minecraft.world.level.ClientLevel] <br>
+	 *
+	 * @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<Void> generateChunks(
 			int chunkPosMinX, int chunkPosMinZ,
@@ -172,6 +172,15 @@ public class ApiEventInjector extends DependencyInjector<IDhApiEvent> 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 <T> the event parameter type
+	 * @return the event parameter wrapped in a {@link DhApiCancelableEventParam} or {@link DhApiEventParam}
+	 */
 	public static <T> DhApiEventParam<T> createEventParamWrapper(IDhApiEvent<T> event, T parameter)
 	{
 		return (event instanceof IDhApiCancelableEvent) ? new DhApiCancelableEventParam<>(parameter) : new DhApiEventParam<>(parameter);
@@ -25,7 +25,7 @@ public interface IDependencyInjector<BindableType extends IBindable>
 	
 	
 	/**
-	 * This does not return incomplete dependencies. <Br>
+	 * Does not return incomplete dependencies. <Br>
 	 * See {@link #get(Class, boolean) get(Class, boolean)} for full documentation.
 	 *
 	 * @see #get(Class, boolean)
@@ -7,12 +7,12 @@ public interface IOverrideInjector<BindableType extends IBindable>
 {
 	/**
 	 * All core overrides should have this priority. <Br>
-	 * 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. */