Add detailed Javadoc comments to NBT tag classes

Enhanced the NBT tag classes with comprehensive Javadoc comments. This improvement adds detailed descriptions and method documentation, aiding developers in understanding and using these classes effectively.

Author: david

nbt/src/main/java/core/nbt/NBTInputStream.java

@@ -14,23 +14,31 @@
 import java.util.Optional;
 import java.util.zip.GZIPInputStream;
 
+/**
+ * An input stream for reading NBT (Named Binary Tag) data.
+ */
 @Getter
 @NullMarked
 public final class NBTInputStream extends DataInputStream {
     private final Charset charset;
 
     /**
-     * @param inputStream the input stream
-     * @throws IOException thrown if something goes wrong
+     * Constructs an {@code NBTInputStream} for reading NBT data from the specified input stream.
+     *
+     * @param inputStream the input stream from which the NBT data is to be read
+     * @throws IOException if an I/O error occurs while reading from the stream
      */
     public NBTInputStream(InputStream inputStream) throws IOException {
         this(inputStream, StandardCharsets.UTF_8);
     }
 
     /**
-     * @param charset     the charset of the content
-     * @param inputStream the input stream
-     * @throws IOException thrown if something goes wrong
+     * Constructs an {@code NBTInputStream} for reading NBT data from the specified input stream
+     * and charset.
+     *
+     * @param inputStream the input stream from which the NBT data is to be read
+     * @param charset     the charset to use for reading string data from the stream
+     * @throws IOException if an I/O error occurs while reading from the stream
      */
     public NBTInputStream(InputStream inputStream, Charset charset) throws IOException {
         super(new DataInputStream(new GZIPInputStream(inputStream)));
@@ -109,6 +117,13 @@ public void registerMapping(int typeId, MappingFunction function) {
      */
     @FunctionalInterface
     public interface MappingFunction {
+        /**
+         * Maps an NBTInputStream to a Tag object.
+         *
+         * @param inputStream the NBTInputStream to be mapped
+         * @return the Tag object mapped from the inputStream
+         * @throws IOException if an I/O error occurs while reading from the stream
+         */
         Tag map(NBTInputStream inputStream) throws IOException;
     }
 }

nbt/src/main/java/core/nbt/NBTOutputStream.java

@@ -3,7 +3,7 @@
 import core.nbt.tag.EscapeTag;
 import core.nbt.tag.Tag;
 import lombok.Getter;
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 import java.io.DataOutputStream;
@@ -13,17 +13,23 @@
 import java.nio.charset.StandardCharsets;
 import java.util.zip.GZIPOutputStream;
 
+/**
+ * A specialized DataOutputStream for writing Named Binary Tag (NBT) data.
+ * This stream supports GZIP compression and allows for writing various
+ * types of NBT tags.
+ */
 @Getter
+@NullMarked
 public final class NBTOutputStream extends DataOutputStream {
-    private final @NonNull Charset charset;
+    private final Charset charset;
 
     /**
      * Create a nbt output stream
      *
      * @param outputStream the stream to write to
      * @throws IOException thrown if something goes wrong
      */
-    public NBTOutputStream(@NonNull OutputStream outputStream) throws IOException {
+    public NBTOutputStream(OutputStream outputStream) throws IOException {
         this(outputStream, StandardCharsets.UTF_8);
     }
 
@@ -34,7 +40,7 @@ public NBTOutputStream(@NonNull OutputStream outputStream) throws IOException {
      * @param outputStream the stream to write to
      * @throws IOException thrown if something goes wrong
      */
-    public NBTOutputStream(@NonNull OutputStream outputStream, @NonNull Charset charset) throws IOException {
+    public NBTOutputStream(OutputStream outputStream, Charset charset) throws IOException {
         super(new GZIPOutputStream(outputStream));
         this.charset = charset;
     }
@@ -47,7 +53,7 @@ public NBTOutputStream(@NonNull OutputStream outputStream, @NonNull Charset char
      * @throws IOException              thrown if something goes wrong
      * @throws IllegalArgumentException thrown if an escape tag was provided
      */
-    public void writeTag(@Nullable String name, @NonNull Tag tag) throws IOException, IllegalArgumentException {
+    public void writeTag(@Nullable String name, Tag tag) throws IOException, IllegalArgumentException {
         if (tag instanceof EscapeTag) throw new IllegalArgumentException("EscapeTag not allowed");
         var bytes = name != null ? name.getBytes(getCharset()) : new byte[0];
         writeByte(tag.getTypeId());

nbt/src/main/java/core/nbt/file/NBTFile.java

@@ -18,11 +18,21 @@
 
 import static java.nio.file.StandardOpenOption.*;
 
+/**
+ * Represents an NBT (Named Binary Tag) file that can be read from and written to.
+ * This class extends the {@link FileIO} class, allowing for operations specific to NBT files.
+ *
+ * @param <R> the type of the root object, which extends {@link CompoundTag}
+ */
 @Getter
 @Setter
 @ToString(callSuper = true)
 @EqualsAndHashCode(callSuper = true)
 public class NBTFile<R extends CompoundTag> extends FileIO<R> {
+    /**
+     * The name of the root tag in an NBT (Named Binary Tag) file.
+     * This variable can be null if no root name is specified.
+     */
     private @Nullable String rootName;
 
     /**

nbt/src/main/java/core/nbt/tag/BooleanTag.java

@@ -2,16 +2,42 @@
 
 import org.jspecify.annotations.NullMarked;
 
+/**
+ * The BooleanTag class represents a boolean value as a byte, where the boolean
+ * value is stored as 0 for false and 1 for true.
+ * This class extends the ByteTag class and provides methods to manipulate boolean values specifically.
+ */
 @NullMarked
 public class BooleanTag extends ByteTag {
+    /**
+     * Constructs a new BooleanTag instance, representing a boolean value as a byte.
+     *
+     * @param value the boolean value to be stored in this tag, where true is
+     *              represented as 1 and false is represented as 0
+     */
     public BooleanTag(boolean value) {
         super((byte) (value ? 1 : 0));
     }
 
+    /**
+     * Sets the byte value based on the provided boolean value.
+     * {@code true} is represented as byte value 1, and {@code false} is represented as byte value 0.
+     *
+     * @param value the boolean value to be converted to a byte and set
+     */
     public void setValue(boolean value) {
         setValue((byte) (value ? 1 : 0));
     }
 
+    /**
+     * Sets the value of this BooleanTag to the specified byte value.
+     * The value must be either 0 or 1. If the value is valid,
+     * it will delegate the setting operation to the superclass method.
+     * If the value is not valid, it throws an IllegalArgumentException.
+     *
+     * @param value the byte value to set, which must be 0 or 1
+     * @throws IllegalArgumentException if the value is not 0 or 1
+     */
     @Override
     public void setValue(Byte value) {
         if (value == 0 || value == 1) super.setValue(value);

nbt/src/main/java/core/nbt/tag/ByteArrayTag.java

@@ -6,10 +6,25 @@
 
 import java.io.IOException;
 
+/**
+ * Represents a tag that contains a byte array.
+ * This class extends {@code ValueTag<byte[]>} and implements {@code IterableTag<Byte>},
+ * providing functionality for handling and manipulating a byte array within an NBT (Named Binary Tag) structure.
+ * It provides methods for reading from and writing to an {@code NBTInputStream}
+ * and {@code NBTOutputStream} respectively.
+ */
 @NullMarked
 public class ByteArrayTag extends ValueTag<byte[]> implements IterableTag<Byte> {
+    /**
+     * Represents the unique identifier for this Tag.
+     */
     public static final int ID = 7;
 
+    /**
+     * Constructs a new ByteArrayTag with the given byte array.
+     *
+     * @param array the byte array to be encapsulated by this tag
+     */
     public ByteArrayTag(byte[] array) {
         super(array);
     }
@@ -40,6 +55,13 @@ public void write(NBTOutputStream outputStream) throws IOException {
         outputStream.write(getValue());
     }
 
+    /**
+     * Reads a ByteArrayTag from the given NBTInputStream.
+     *
+     * @param inputStream the NBT input stream to read the byte array from
+     * @return a ByteArrayTag containing the byte array read from the input stream
+     * @throws IOException if an I/O error occurs while reading from the input stream
+     */
     public static ByteArrayTag read(NBTInputStream inputStream) throws IOException {
         var length = inputStream.readInt();
         var bytes = new byte[length];

nbt/src/main/java/core/nbt/tag/ByteTag.java

@@ -6,14 +6,32 @@
 
 import java.io.IOException;
 
+/**
+ * The ByteTag class represents a byte value in the tag structure.
+ * It extends the NumberTag class with Byte as the specific number type.
+ * This class provides methods to manipulate the byte value and read/write it to an NBT stream.
+ */
 @NullMarked
 public class ByteTag extends NumberTag<Byte> {
+    /**
+     * Represents the unique identifier for this Tag.
+     */
     public static final int ID = 1;
 
+    /**
+     * Constructs a new ByteTag instance with the specified byte value.
+     *
+     * @param value the byte value to be stored in this tag
+     */
     public ByteTag(Byte value) {
         super(value);
     }
 
+    @Override
+    public boolean getAsBoolean() {
+        return getValue() == 1;
+    }
+
     @Override
     public byte getAsByte() {
         return getValue();
@@ -29,12 +47,14 @@ public void write(NBTOutputStream outputStream) throws IOException {
         outputStream.write(getValue());
     }
 
+    /**
+     * Reads a byte value from the provided NBTInputStream and returns it as a ByteTag.
+     *
+     * @param inputStream the NBTInputStream to read the byte value from
+     * @return a ByteTag containing the read byte value
+     * @throws IOException if an I/O error occurs while reading from the input stream
+     */
     public static ByteTag read(NBTInputStream inputStream) throws IOException {
         return new ByteTag(inputStream.readByte());
     }
-
-    @Override
-    public boolean getAsBoolean() {
-        return getValue() == 1;
-    }
 }