Annotated serialization interfaces with @Contract

Added `@Contract` annotations to methods in serialization-related interfaces to enhance code contracts, improve purity clarity, and document immutability expectations.

Author: NonSwag

nbt/src/main/java/core/nbt/serialization/NBT.java

@@ -17,6 +17,7 @@ public sealed interface NBT extends TagSerializationContext, TagDeserializationC
      *
      * @return a new Builder instance for constructing NBT objects
      */
+    @Contract(value = " -> new", pure = true)
     static Builder builder() {
         return new SimpleNBT.Builder();
     }
@@ -30,6 +31,7 @@ static Builder builder() {
      * @return the deserialized object of the specified type
      * @deprecated use {@link #deserialize(Tag, Class)} instead
      */
+    @Contract(pure = true)
     @Deprecated(forRemoval = true, since = "2.4.0")
     default <T> T fromTag(Tag tag, Class<T> type) {
         return deserialize(tag, type);
@@ -44,6 +46,7 @@ default <T> T fromTag(Tag tag, Class<T> type) {
      * @return the deserialized object of the specified type
      * @deprecated use {@link #deserialize(Tag, Type)} instead
      */
+    @Contract(pure = true)
     @Deprecated(forRemoval = true, since = "2.4.0")
     default <T> T fromTag(Tag tag, Type type) {
         return deserialize(tag, type);
@@ -56,6 +59,7 @@ default <T> T fromTag(Tag tag, Type type) {
      * @return the Tag representation of the provided object
      * @deprecated use {@link #serialize(Object)} instead
      */
+    @Contract(value = "_ -> new", pure = true)
     @Deprecated(forRemoval = true, since = "2.4.0")
     default Tag toTag(Object object) {
         return serialize(object);
@@ -69,6 +73,7 @@ default Tag toTag(Object object) {
      * @return the serialized tag representation of the object
      * @deprecated use {@link #serialize(Object, Class)} instead
      */
+    @Contract(value = "_, _ -> new", pure = true)
     @Deprecated(forRemoval = true, since = "2.4.0")
     default Tag toTag(Object object, Class<?> type) {
         return serialize(object, type);
@@ -82,6 +87,7 @@ default Tag toTag(Object object, Class<?> type) {
      * @return the serialized tag representation of the object
      * @deprecated use {@link #serialize(Object, Type)} instead
      */
+    @Contract(value = "_, _ -> new", pure = true)
     @Deprecated(forRemoval = true, since = "2.4.0")
     default Tag toTag(Object object, Type type) {
         return serialize(object, type);

nbt/src/main/java/core/nbt/serialization/TagDeserializationContext.java

@@ -1,6 +1,7 @@
 package core.nbt.serialization;
 
 import core.nbt.tag.Tag;
+import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NullMarked;
 
 import java.lang.reflect.Type;
@@ -19,6 +20,7 @@ public interface TagDeserializationContext {
      * @return an object of the specified type deserialized from the tag
      * @throws ParserException if an error occurs during deserialization
      */
+    @Contract(pure = true)
     <T> T deserialize(Tag tag, Class<T> type) throws ParserException;
 
     /**
@@ -30,5 +32,6 @@ public interface TagDeserializationContext {
      * @return an object of the specified type deserialized from the tag
      * @throws ParserException if an error occurs during deserialization
      */
+    @Contract(pure = true)
     <T> T deserialize(Tag tag, Type type) throws ParserException;
 }

nbt/src/main/java/core/nbt/serialization/TagDeserializer.java

@@ -1,6 +1,7 @@
 package core.nbt.serialization;
 
 import core.nbt.tag.Tag;
+import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -18,5 +19,6 @@ public interface TagDeserializer<T> {
      * @return the deserialized object of type T
      * @throws ParserException if an error occurs during deserialization
      */
+    @Contract(pure = true)
     T deserialize(Tag tag, TagDeserializationContext context) throws ParserException;
 }

nbt/src/main/java/core/nbt/serialization/TagSerializable.java

@@ -1,6 +1,7 @@
 package core.nbt.serialization;
 
 import core.nbt.tag.Tag;
+import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -15,6 +16,7 @@ public interface TagSerializable {
      * @return the serialized Tag representation of the current object
      * @throws ParserException if an error occurs during serialization
      */
+    @Contract(value = " -> new", pure = true)
     Tag serialize() throws ParserException;
 
     /**
@@ -23,5 +25,6 @@ public interface TagSerializable {
      * @param tag the Tag object to be deserialized
      * @throws ParserException if an error occurs during deserialization
      */
+    @Contract(mutates = "this")
     void deserialize(Tag tag) throws ParserException;
 }

nbt/src/main/java/core/nbt/serialization/TagSerializationContext.java

@@ -1,6 +1,7 @@
 package core.nbt.serialization;
 
 import core.nbt.tag.Tag;
+import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NullMarked;
 
 import java.lang.reflect.Type;
@@ -17,6 +18,7 @@ public interface TagSerializationContext {
      * @return the serialized Tag representation of the object
      * @throws ParserException if an error occurs during serialization
      */
+    @Contract(value = "_ -> new", pure = true)
     Tag serialize(Object object) throws ParserException;
 
     /**
@@ -27,6 +29,7 @@ public interface TagSerializationContext {
      * @return the serialized Tag representation of the object
      * @throws ParserException if an error occurs during serialization
      */
+    @Contract(value = "_, _ -> new", pure = true)
     Tag serialize(Object object, Class<?> type) throws ParserException;
 
     /**
@@ -37,5 +40,6 @@ public interface TagSerializationContext {
      * @return the serialized Tag representation of the object
      * @throws ParserException if an error occurs during serialization
      */
+    @Contract(value = "_, _ -> new", pure = true)
     Tag serialize(Object object, Type type) throws ParserException;
 }

nbt/src/main/java/core/nbt/serialization/TagSerializer.java

@@ -1,6 +1,7 @@
 package core.nbt.serialization;
 
 import core.nbt.tag.Tag;
+import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -18,5 +19,6 @@ public interface TagSerializer<T> {
      * @return the Tag representation of the provided vector
      * @throws ParserException if an error occurs during serialization
      */
+    @Contract(value = "_, _ -> new", pure = true)
     Tag serialize(T object, TagSerializationContext context) throws ParserException;
 }