From f99bd2655ff6a920d5743baf1de2f85d66367925 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20N=C3=BCcke?= Date: Sat, 5 Dec 2020 18:03:38 +0100 Subject: [PATCH] Satisfy javadoc linter. --- build.gradle | 2 +- src/main/java/li/cil/oc2/api/API.java | 2 +- src/main/java/li/cil/oc2/api/bus/Device.java | 2 +- .../li/cil/oc2/api/bus/device/object/Callback.java | 6 ++++++ .../li/cil/oc2/api/bus/device/object/Callbacks.java | 2 +- .../li/cil/oc2/api/bus/device/object/Parameter.java | 4 ++++ .../li/cil/oc2/api/bus/device/rpc/RPCDevice.java | 4 ++++ .../li/cil/oc2/api/bus/device/rpc/RPCMethod.java | 12 ++++++++++++ .../li/cil/oc2/api/bus/device/rpc/RPCParameter.java | 4 ++++ .../java/li/cil/oc2/api/provider/DeviceProvider.java | 2 +- 10 files changed, 35 insertions(+), 5 deletions(-) diff --git a/build.gradle b/build.gradle index c6c763fc..1e01b240 100644 --- a/build.gradle +++ b/build.gradle @@ -44,7 +44,7 @@ archivesBaseName = "${mod_name}-MC${minecraft_version}" sourceCompatibility = targetCompatibility = JavaVersion.VERSION_1_8 compileJava.sourceCompatibility = compileJava.targetCompatibility = JavaVersion.VERSION_1_8 -javadoc.options.addStringOption('Xdoclint:none', '-quiet') +//javadoc.options.addStringOption('Xdoclint:none', '-quiet') configurations { embed diff --git a/src/main/java/li/cil/oc2/api/API.java b/src/main/java/li/cil/oc2/api/API.java index 0d547666..f611c38b 100644 --- a/src/main/java/li/cil/oc2/api/API.java +++ b/src/main/java/li/cil/oc2/api/API.java @@ -16,7 +16,7 @@ public final class API { *

* Example: * 

-     * InterModComms.sendTo(API.MOD_ID, API.IMC_ADD_DEVICE_PROVIDER, () -> new DeviceProvider() { ... });
+     * InterModComms.sendTo(API.MOD_ID, API.IMC_ADD_DEVICE_PROVIDER, () -> new DeviceProvider() { ... });
      *
*/ public static final String IMC_ADD_DEVICE_PROVIDER = "addDeviceProvider"; diff --git a/src/main/java/li/cil/oc2/api/bus/Device.java b/src/main/java/li/cil/oc2/api/bus/Device.java index 8a6c8851..01829e1e 100644 --- a/src/main/java/li/cil/oc2/api/bus/Device.java +++ b/src/main/java/li/cil/oc2/api/bus/Device.java @@ -7,7 +7,7 @@ package li.cil.oc2.api.bus; * managing the bus. *

* Note that it is strongly encouraged for implementations to provide an overloaded - * {@link #equals(Object)} and {@link #hashCode()} so that identical devices can be + * {@link Object#equals(Object)} and {@link Object#hashCode()} so that identical devices can be * detected. */ public interface Device { diff --git a/src/main/java/li/cil/oc2/api/bus/device/object/Callback.java b/src/main/java/li/cil/oc2/api/bus/device/object/Callback.java index f8ed367e..9df36c1a 100644 --- a/src/main/java/li/cil/oc2/api/bus/device/object/Callback.java +++ b/src/main/java/li/cil/oc2/api/bus/device/object/Callback.java @@ -29,16 +29,22 @@ public @interface Callback { * Use this when the targeted method interacts with data that is not thread * safe, for example the world or any objects inside the world, such as * tile entities and entities. + * + * @return {@code true} when to be executed on main thread; {@code false} otherwise. */ boolean synchronize() default true; /** * Option VM visible documentation of this method. + * + * @return the description of the method. */ String description() default ""; /** * Optional VM visible documentation of the values returned by this method. + * + * @return the description of the return value. */ String returnValueDescription() default ""; } diff --git a/src/main/java/li/cil/oc2/api/bus/device/object/Callbacks.java b/src/main/java/li/cil/oc2/api/bus/device/object/Callbacks.java index a44b5d64..a480772c 100644 --- a/src/main/java/li/cil/oc2/api/bus/device/object/Callbacks.java +++ b/src/main/java/li/cil/oc2/api/bus/device/object/Callbacks.java @@ -38,7 +38,7 @@ public final class Callbacks { * public void f(String a) { } * } * - * List methods = Callbacks.collectMethods(new Example()); + * List<RPCMethod> methods = Callbacks.collectMethods(new Example()); * methods.get(0).invoke("argument"); * * diff --git a/src/main/java/li/cil/oc2/api/bus/device/object/Parameter.java b/src/main/java/li/cil/oc2/api/bus/device/object/Parameter.java index f743bf65..6ac838e9 100644 --- a/src/main/java/li/cil/oc2/api/bus/device/object/Parameter.java +++ b/src/main/java/li/cil/oc2/api/bus/device/object/Parameter.java @@ -20,11 +20,15 @@ import java.lang.annotation.Target; public @interface Parameter { /** * The name of the parameter as seen by the VM. + * + * @return the name of the parameter. */ String value(); /** * Optional VM visible documentation of this parameter. + * + * @return the description of the parameter. */ String description() default ""; } diff --git a/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCDevice.java b/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCDevice.java index ad8a302e..6df0761c 100644 --- a/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCDevice.java +++ b/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCDevice.java @@ -32,11 +32,15 @@ public interface RPCDevice extends Device { *

* In a more general sense, these can be considered tags the device can be * referenced by inside a VM. + * + * @return the list of type names. */ List getTypeNames(); /** * The list of methods provided by this interface. + * + * @return the list of methods. */ List getMethods(); } diff --git a/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCMethod.java b/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCMethod.java index 97747a96..1c8902f0 100644 --- a/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCMethod.java +++ b/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCMethod.java @@ -25,21 +25,29 @@ public interface RPCMethod { * When invoked through a {@link DeviceBusController} this is what the method * will be referenced by, so the name should be unlikely to be duplicated in * another device to avoid ambiguity when devices are combined. + * + * @return the name of the method. */ String getName(); /** * When {@code true}, invocations of this method will be synchronized to the main thread. + * + * @return {@code true} when to be executed on main thread; {@code false} otherwise. */ boolean isSynchronized(); /** * The type of the values returned by this method. + * + * @return the returned type. */ Class getReturnType(); /** * The list of parameters this method accepts. + * + * @return the list of parameters. */ RPCParameter[] getParameters(); @@ -68,6 +76,8 @@ public interface RPCMethod { * An optional description of the method. *

* May be used inside VMs to generate documentation. + * + * @return the method description. */ default Optional getDescription() { return Optional.empty(); @@ -77,6 +87,8 @@ public interface RPCMethod { * An optional description of the return value of this method. *

* May be used inside VMs to generate documentation. + * + * @return the return value description. */ default Optional getReturnValueDescription() { return Optional.empty(); diff --git a/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCParameter.java b/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCParameter.java index 2e8c8c6c..e0fc5861 100644 --- a/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCParameter.java +++ b/src/main/java/li/cil/oc2/api/bus/device/rpc/RPCParameter.java @@ -24,6 +24,8 @@ public interface RPCParameter { * An optional name of the parameter. *

* May be used inside VMs to generate documentation. + * + * @return the name of the parameter. */ default Optional getName() { return Optional.empty(); @@ -33,6 +35,8 @@ public interface RPCParameter { * An optional description of the parameter. *

* May be used inside VMs to generate documentation. + * + * @return the description of the parameter. */ default Optional getDescription() { return Optional.empty(); diff --git a/src/main/java/li/cil/oc2/api/provider/DeviceProvider.java b/src/main/java/li/cil/oc2/api/provider/DeviceProvider.java index 69458796..cf0857cb 100644 --- a/src/main/java/li/cil/oc2/api/provider/DeviceProvider.java +++ b/src/main/java/li/cil/oc2/api/provider/DeviceProvider.java @@ -21,7 +21,7 @@ import net.minecraftforge.common.util.LazyOptional; * Implementations should return the same device for the same query. *

* Failing that, implementations should return instances that are equal to each - * other when compared using {@link #equals(Object)} and have equal {@link #hashCode()}s. + * other when compared using {@link Object#equals(Object)} and have equal {@link Object#hashCode()}s. *

* This is required to avoid device duplication when a device is connected to a bus more * than once (e.g. for blocks when connected cables are adjacent to multiple faces of the