From b23c01c44b90d00f053a9167f365fedf68090d97 Mon Sep 17 00:00:00 2001 From: KennyTV Date: Thu, 8 Apr 2021 10:58:54 +0200 Subject: [PATCH] Javadoc additions --- .../java/us/myles/ViaVersion/ViaManager.java | 45 ++++++++++ .../api/data/MappingDataLoader.java | 4 + .../ViaVersion/api/entities/EntityType.java | 11 +++ .../api/minecraft/BlockChangeRecord.java | 8 ++ .../api/minecraft/chunks/Chunk.java | 14 ++- .../ViaVersion/api/protocol/PacketType.java | 8 +- .../api/protocol/ProtocolPathKey.java | 4 + .../api/protocol/ProtocolVersion.java | 86 ++++++++++++++++++- .../ViaVersion/api/protocol/VersionRange.java | 15 ++++ .../myles/ViaVersion/util/EntityTypeUtil.java | 14 +++ .../ViaVersion/util/UnsupportedSoftware.java | 15 ++++ .../us/myles/ViaVersion/util/VersionInfo.java | 7 ++ build.gradle.kts | 1 + 13 files changed, 223 insertions(+), 9 deletions(-) diff --git a/api/src/main/java/us/myles/ViaVersion/ViaManager.java b/api/src/main/java/us/myles/ViaVersion/ViaManager.java index 233071202..f45cfa42b 100644 --- a/api/src/main/java/us/myles/ViaVersion/ViaManager.java +++ b/api/src/main/java/us/myles/ViaVersion/ViaManager.java @@ -34,22 +34,67 @@ import java.util.Set; public interface ViaManager { + /** + * Returns the protocol manager for registering/getting protocols and their mapping data loading. + * + * @return protocol manager + */ ProtocolManager getProtocolManager(); + /** + * Returns platform for handling platform specific configuration, tasks, and plugin data. + * + * @return platform + */ ViaPlatform getPlatform(); + /** + * Returns the userconnection manager for handling clients connected to the server. + * + * @return userconnection manager + */ ViaConnectionManager getConnectionManager(); + /** + * Returns the manager for Via providers. + * + * @return provider manager + */ ViaProviders getProviders(); + /** + * Returns the injector for injecting netty handlers and initially getting the server protocol version. + * + * @return injector + */ ViaInjector getInjector(); + /** + * Returns the command handler for managing ViaVersion subcommands. + * + * @return command handler + */ ViaVersionCommand getCommandHandler(); + /** + * Returns the platform loader responsible for registering listeners, providers and such. + * + * @return platform loader + */ ViaPlatformLoader getLoader(); + /** + * If debug is enabled, packets and other otherwise suppressed warnings will be logged. + * + * @return true if enabled + */ boolean isDebug(); + /** + * Sets the debug mode. If enabled, packets and other otherwise suppressed warnings will be logged. + * + * @param debug whether debug should be enabled + */ void setDebug(boolean debug); /** diff --git a/api/src/main/java/us/myles/ViaVersion/api/data/MappingDataLoader.java b/api/src/main/java/us/myles/ViaVersion/api/data/MappingDataLoader.java index bdfc4e3af..43b07f5ac 100644 --- a/api/src/main/java/us/myles/ViaVersion/api/data/MappingDataLoader.java +++ b/api/src/main/java/us/myles/ViaVersion/api/data/MappingDataLoader.java @@ -205,6 +205,8 @@ public class MappingDataLoader { } /** + * Returns a map of the object entries hashed by their id value. + * * @param object json object * @return map with indexes hashed by their id value */ @@ -218,6 +220,8 @@ public class MappingDataLoader { } /** + * Returns a map of the array entries hashed by their id value. + * * @param array json array * @return map with indexes hashed by their id value */ diff --git a/api/src/main/java/us/myles/ViaVersion/api/entities/EntityType.java b/api/src/main/java/us/myles/ViaVersion/api/entities/EntityType.java index 17c77c4e2..50cf5fa82 100644 --- a/api/src/main/java/us/myles/ViaVersion/api/entities/EntityType.java +++ b/api/src/main/java/us/myles/ViaVersion/api/entities/EntityType.java @@ -27,15 +27,24 @@ import org.checkerframework.checker.nullness.qual.Nullable; public interface EntityType { /** + * Returns the entity id. + * * @return entity id */ int getId(); /** + * Returns the parent entity type if present. + * * @return parent entity type if present */ @Nullable EntityType getParent(); + /** + * Returns the entity type name, not necessarily matching the Vanilla type name. + * + * @return entity type name + */ String name(); default boolean is(EntityType... types) { @@ -52,6 +61,8 @@ public interface EntityType { } /** + * Returns whether the current type is equal to the given type, or has it as a parent type. + * * @param type entity type to check against * @return true if the current type is equal to the given type, or has it as a parent type */ diff --git a/api/src/main/java/us/myles/ViaVersion/api/minecraft/BlockChangeRecord.java b/api/src/main/java/us/myles/ViaVersion/api/minecraft/BlockChangeRecord.java index 97988fe8e..aa82b6185 100644 --- a/api/src/main/java/us/myles/ViaVersion/api/minecraft/BlockChangeRecord.java +++ b/api/src/main/java/us/myles/ViaVersion/api/minecraft/BlockChangeRecord.java @@ -25,21 +25,29 @@ package us.myles.ViaVersion.api.minecraft; public interface BlockChangeRecord { /** + * Returns the relative x coordinate within the chunk section. + * * @return relative x coordinate within the chunk section */ byte getSectionX(); /** + * Returns the relative y coordinate within the chunk section. + * * @return relative y coordinate within the chunk section */ byte getSectionY(); /** + * Returns the relative z coordinate within the chunk section. + * * @return relative z coordinate within the chunk section */ byte getSectionZ(); /** + * Returns the absolute y coordinate based on the given chunk section y. + * * @param chunkSectionY chunk section * @return absolute y coordinate */ diff --git a/api/src/main/java/us/myles/ViaVersion/api/minecraft/chunks/Chunk.java b/api/src/main/java/us/myles/ViaVersion/api/minecraft/chunks/Chunk.java index dd9a55d20..9e2d276e1 100644 --- a/api/src/main/java/us/myles/ViaVersion/api/minecraft/chunks/Chunk.java +++ b/api/src/main/java/us/myles/ViaVersion/api/minecraft/chunks/Chunk.java @@ -35,12 +35,16 @@ public interface Chunk { int getZ(); /** - * @return whether this chunk holds biome data, always true for 1.17+ chunks + * Returns whether this chunk holds biome data, always true for 1.17+ chunks. + * + * @return true if this chunk holds biome data */ boolean isBiomeData(); /** - * @return whether this is a full chunk, always true for 1.17+ chunks + * Returns whether this is a full chunk, always true for 1.17+ chunks. + * + * @return true if this is a full chunk */ boolean isFullChunk(); @@ -54,6 +58,8 @@ public interface Chunk { void setIgnoreOldLightData(boolean ignoreOldLightData); /** + * Returns the chunk section bit mask for chunks < 1.17. + * * @return chunk section bit mask for chunks < 1.17 * @see #getChunkMask() */ @@ -62,7 +68,9 @@ public interface Chunk { void setBitmask(int bitmask); /** - * @return chunk section bit mask, only non-null available for 1.17+ chunks + * Returns the chunk section bit mask, only non-null for 1.17+ chunks. + * + * @return chunk section bit mask, only non-null for 1.17+ chunks * @see #getBitmask() */ @Nullable BitSet getChunkMask(); diff --git a/api/src/main/java/us/myles/ViaVersion/api/protocol/PacketType.java b/api/src/main/java/us/myles/ViaVersion/api/protocol/PacketType.java index 1b81a5628..fc00a2b05 100644 --- a/api/src/main/java/us/myles/ViaVersion/api/protocol/PacketType.java +++ b/api/src/main/java/us/myles/ViaVersion/api/protocol/PacketType.java @@ -31,12 +31,16 @@ package us.myles.ViaVersion.api.protocol; public interface PacketType { /** - * @return name of the packet, to be consistent over multiple versions + * Returns the name of the packet, to be consistent over multiple versions. + * + * @return name of the packet */ String name(); /** - * @return ordinal, being the packet id for the implemented protocol + * Returns the ordinal, being the packet id for the implemented protocol. + * + * @return packet id for the implemented protocol */ int ordinal(); } diff --git a/api/src/main/java/us/myles/ViaVersion/api/protocol/ProtocolPathKey.java b/api/src/main/java/us/myles/ViaVersion/api/protocol/ProtocolPathKey.java index 0fbde00fe..ab664ccb5 100644 --- a/api/src/main/java/us/myles/ViaVersion/api/protocol/ProtocolPathKey.java +++ b/api/src/main/java/us/myles/ViaVersion/api/protocol/ProtocolPathKey.java @@ -25,11 +25,15 @@ package us.myles.ViaVersion.api.protocol; public interface ProtocolPathKey { /** + * Returns the client protocol version. + * * @return client protocol version */ int getClientProtocolVersion(); /** + * Returns the server protocol version. + * * @return server protocol version */ int getServerProtocolVersion(); diff --git a/api/src/main/java/us/myles/ViaVersion/api/protocol/ProtocolVersion.java b/api/src/main/java/us/myles/ViaVersion/api/protocol/ProtocolVersion.java index 26b8a1d7e..7b7d869aa 100644 --- a/api/src/main/java/us/myles/ViaVersion/api/protocol/ProtocolVersion.java +++ b/api/src/main/java/us/myles/ViaVersion/api/protocol/ProtocolVersion.java @@ -30,7 +30,7 @@ import org.checkerframework.checker.nullness.qual.Nullable; import java.util.ArrayList; import java.util.Collections; -import java.util.HashSet; +import java.util.LinkedHashSet; import java.util.List; import java.util.Set; @@ -91,6 +91,15 @@ public class ProtocolVersion { return register(version, -1, name, versionRange); } + /** + * Registers a protocol version. + * + * @param version release protocol version + * @param snapshotVersion snapshot protocol version, or -1 if not a snapshot + * @param name version name + * @param versionRange range of versions that are supported by this protocol version, null if not a range + * @return registered {@link ProtocolVersion} + */ public static ProtocolVersion register(int version, int snapshotVersion, String name, @Nullable VersionRange versionRange) { ProtocolVersion protocol = new ProtocolVersion(version, snapshotVersion, name, versionRange); versionList.add(protocol); @@ -101,10 +110,23 @@ public class ProtocolVersion { return protocol; } + /** + * Returns whether a protocol with the given protocol version is registered. + * + * @param id protocol version + * @return true if this protocol version has been registered + */ public static boolean isRegistered(int id) { return versions.containsKey(id); } + /** + * Returns a {@link ProtocolVersion} instance, even if this protocol version + * has not been registered. See {@link #isRegistered(int)} berorehand or {@link #isKnown()}. + * + * @param id protocol version + * @return registered or unknown {@link ProtocolVersion} + */ public static @NonNull ProtocolVersion getProtocol(int id) { ProtocolVersion protocolVersion = versions.get(id); if (protocolVersion != null) { @@ -114,14 +136,33 @@ public class ProtocolVersion { } } + /** + * Returns the internal index of the stored protocol version. + * + * @param version protocol version instance + * @return internal index of the stored protocol version + */ public static int getIndex(ProtocolVersion version) { return versionList.indexOf(version); } + /** + * Returns an immutable list of registered protocol versions. + * + * @return immutable list of registered protocol versions + */ public static List getProtocols() { return Collections.unmodifiableList(new ArrayList<>(versions.values())); } + /** + * Returns the registered protocol version if present, else null. + * This accepts the actual registered names (like "1.16.4/5") as well as + * included versions for version ranges and wildcards. + * + * @param protocol version name, e.g. "1.16.3" + * @return registered protocol version if present, else null + */ public static @Nullable ProtocolVersion getClosest(String protocol) { for (ProtocolVersion version : versions.values()) { String name = version.getName(); @@ -150,10 +191,20 @@ public class ProtocolVersion { private final boolean versionWildcard; private final Set includedVersions; + /** + * @param version protocol version + * @param name version name + */ public ProtocolVersion(int version, String name) { this(version, -1, name, null); } + /** + * @param version protocol version + * @param snapshotVersion actual snapshot protocol version, -1 if not a snapshot + * @param name version name + * @param versionRange range of versions that are supported by this protocol version, null if not a range + */ public ProtocolVersion(int version, int snapshotVersion, String name, @Nullable VersionRange versionRange) { this.version = version; this.snapshotVersion = snapshotVersion; @@ -162,7 +213,7 @@ public class ProtocolVersion { Preconditions.checkArgument(!versionWildcard || versionRange == null, "A version cannot be a wildcard and a range at the same time!"); if (versionRange != null) { - includedVersions = new HashSet<>(); + includedVersions = new LinkedHashSet<>(); for (int i = versionRange.getRangeFrom(); i <= versionRange.getRangeTo(); i++) { if (i == 0) { includedVersions.add(versionRange.getBaseVersion()); // Keep both the base version and with ".0" appended @@ -176,6 +227,8 @@ public class ProtocolVersion { } /** + * Returns the release protocol version. + * * @return release version */ public int getVersion() { @@ -183,6 +236,8 @@ public class ProtocolVersion { } /** + * Returns the snapshot protocol version without the snapshot indicator bit if this is a snapshot protocol version. + * * @return snapshot protocol version without the snapshot indicator bit * @throws IllegalArgumentException if the version if not a snapshot version * @see #isSnapshot() @@ -193,6 +248,8 @@ public class ProtocolVersion { } /** + * Returns the snapshot protocol version with the snapshot indicator bit if this is a snapshot protocol version. + * * @return snapshot protocol version with the snapshot indicator bit * @throws IllegalArgumentException if the version if not a snapshot version * @see #isSnapshot() @@ -203,18 +260,27 @@ public class ProtocolVersion { } /** + * Returns the release version if release, snapshot version (with the snapshot indicator bit) if snapshot. + * * @return release version if release, snapshot version (with the snapshot indicator bit) if snapshot */ public int getOriginalVersion() { return snapshotVersion == -1 ? version : ((1 << 30) | snapshotVersion); } + /** + * Returns whether the protocol is set. Should only be unknown for unregistered protocols returned by {@link #getProtocol(int)}. + * + * @return true if the protocol is set + */ public boolean isKnown() { return version != -1; } /** - * @return true if the protocol includes a range of versions (but not an entire major version range), for example 1.7-1.7.5 + * Returns whether the protocol includes a range of versions (but not an entire major version range), for example 1.7-1.7.5. + * + * @return true if the protocol includes a range of versions * @see #getIncludedVersions() */ public boolean isRange() { @@ -234,16 +300,28 @@ public class ProtocolVersion { } /** - * @return true if the protocol includes an entire major version range (for example 1.8.x) + * Returns whether the protocol includes an entire major version range (for example 1.8.x). + * + * @return true if the protocol includes an entire major version range */ public boolean isVersionWildcard() { return versionWildcard; } + /** + * Returns the version name. + * + * @return version name + */ public String getName() { return name; } + /** + * Returns whether this represents a snapshot version. + * + * @return true if this represents a snapshot version, false otherwise + */ public boolean isSnapshot() { return snapshotVersion != -1; } diff --git a/api/src/main/java/us/myles/ViaVersion/api/protocol/VersionRange.java b/api/src/main/java/us/myles/ViaVersion/api/protocol/VersionRange.java index 83d7d5a9b..70c0e3911 100644 --- a/api/src/main/java/us/myles/ViaVersion/api/protocol/VersionRange.java +++ b/api/src/main/java/us/myles/ViaVersion/api/protocol/VersionRange.java @@ -45,14 +45,29 @@ public class VersionRange { this.rangeTo = rangeTo; } + /** + * Returns the major version name. + * + * @return major version name + */ public String getBaseVersion() { return baseVersion; } + /** + * Returns the lowest included minor version. + * + * @return lowest included minor version + */ public int getRangeFrom() { return rangeFrom; } + /** + * Returns the highest included minor version. + * + * @return highest included minor version + */ public int getRangeTo() { return rangeTo; } diff --git a/api/src/main/java/us/myles/ViaVersion/util/EntityTypeUtil.java b/api/src/main/java/us/myles/ViaVersion/util/EntityTypeUtil.java index 39bca18b1..e9469a42b 100644 --- a/api/src/main/java/us/myles/ViaVersion/util/EntityTypeUtil.java +++ b/api/src/main/java/us/myles/ViaVersion/util/EntityTypeUtil.java @@ -31,6 +31,12 @@ import java.util.List; public class EntityTypeUtil { + /** + * Returns an ordered array with each index representing the actual entity id. + * + * @param values entity types + * @return ordered array with each index representing the actual entity id + */ public static EntityType[] toOrderedArray(EntityType[] values) { List types = new ArrayList<>(); for (EntityType type : values) { @@ -43,6 +49,14 @@ public class EntityTypeUtil { return types.toArray(new EntityType[0]); } + /** + * Returns the entity type from id, or the given fallback if out of bounds. + * + * @param values sorted entity type array + * @param typeId entity type id + * @param fallback fallback/base entity type + * @return entity type from id + */ public static EntityType getTypeFromId(EntityType[] values, int typeId, EntityType fallback) { EntityType type; if (typeId < 0 || typeId >= values.length || (type = values[typeId]) == null) { diff --git a/api/src/main/java/us/myles/ViaVersion/util/UnsupportedSoftware.java b/api/src/main/java/us/myles/ViaVersion/util/UnsupportedSoftware.java index 5235f2452..0cf30b221 100644 --- a/api/src/main/java/us/myles/ViaVersion/util/UnsupportedSoftware.java +++ b/api/src/main/java/us/myles/ViaVersion/util/UnsupportedSoftware.java @@ -34,14 +34,29 @@ public final class UnsupportedSoftware { this.reason = reason; } + /** + * Returns the software name. + * + * @return software name + */ public String getName() { return name; } + /** + * Returns the fully qualified class name. + * + * @return fully qualified class name + */ public String getClassName() { return className; } + /** + * Returns the reason for being unsupported by Via. + * + * @return reason for being unsupported + */ public String getReason() { return reason; } diff --git a/api/src/main/java/us/myles/ViaVersion/util/VersionInfo.java b/api/src/main/java/us/myles/ViaVersion/util/VersionInfo.java index 5b3437419..b184f93c1 100644 --- a/api/src/main/java/us/myles/ViaVersion/util/VersionInfo.java +++ b/api/src/main/java/us/myles/ViaVersion/util/VersionInfo.java @@ -22,7 +22,14 @@ */ package us.myles.ViaVersion.util; +import us.myles.ViaVersion.api.platform.ViaPlatform; + public class VersionInfo { + /** + * Plugin version. + * + * @see ViaPlatform#getPluginVersion() + */ public static final String VERSION = "$VERSION"; } diff --git a/build.gradle.kts b/build.gradle.kts index 1632f99dd..90c319338 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -57,6 +57,7 @@ subprojects { } dependencies { + // Note: If manually starting tests doesn't work for you in IJ, change 'Gradle -> Run Tests Using' to 'IntelliJ IDEA' testImplementation("io.netty", "netty-all", Versions.netty) testImplementation("com.google.guava", "guava", Versions.guava) testImplementation("org.junit.jupiter", "junit-jupiter-api", Versions.jUnit)