some java docs

src/main/java/com/cleanroommc/groovyscript/api/GroovyPlugin.java

@@ -23,6 +23,9 @@ public interface GroovyPlugin extends IGroovyContainer {
         return createModPropertyContainer();
     }
 
+    /**
+     * @deprecated use {@link #createGroovyPropertyContainer()} instead
+     */
     @GroovyBlacklist
     @ApiStatus.OverrideOnly
     @Deprecated

src/main/java/com/cleanroommc/groovyscript/api/IRegistrar.java

@@ -7,9 +7,7 @@
 import java.lang.reflect.Modifier;
 
 /**
- * A helper interface to register {@link INamed registries} without having direct access to the
- * {@link com.cleanroommc.groovyscript.compat.mods.GroovyPropertyContainer GroovyPropertyContainer}.
- * An instance can be obtained from {@link GroovyContainer#getRegistrar()}.
+ * @deprecated The methods of this class have been added directly to {@link GroovyContainer}
  */
 @ApiStatus.ScheduledForRemoval(inVersion = "1.2.0")
 @Deprecated
@@ -21,6 +19,7 @@ public interface IRegistrar {
      *
      * @param registry registry to add.
      */
+    @Deprecated
     void addRegistry(INamed registry);
 
     /**
@@ -29,6 +28,7 @@ public interface IRegistrar {
      *
      * @param object object to add fields from
      */
+    @Deprecated
     default void addFieldsOf(Object object) {
         boolean staticOnly = false;
         Class<?> clazz;

src/main/java/com/cleanroommc/groovyscript/compat/mods/GroovyContainer.java

@@ -7,6 +7,13 @@
 import com.cleanroommc.groovyscript.mapper.ObjectMapper;
 import org.jetbrains.annotations.ApiStatus;
 
+/**
+ * This is the base class for mod compat. It is created even if the other mod is not loaded.
+ * For compat inside GroovyScript use {@link InternalModContainer}.
+ * Otherwise, take a look at {@link com.cleanroommc.groovyscript.api.GroovyPlugin}.
+ *
+ * @param <T> type of the property container
+ */
 @ApiStatus.NonExtendable
 public abstract class GroovyContainer<T extends GroovyPropertyContainer> implements IGroovyContainer {
 
@@ -17,13 +24,19 @@ public String toString() {
         return getContainerName();
     }
 
+    /**
+     * @deprecated Use {@link #addProperty(INamed)} and {@link #addPropertiesOfFields(Object, boolean)} from this class instead.
+     */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "1.2.0")
     @GroovyBlacklist
     public IRegistrar getVirtualizedRegistrar() {
         return getRegistrar();
     }
 
+    /**
+     * @deprecated Use {@link #addProperty(INamed)} and {@link #addPropertiesOfFields(Object, boolean)} from this class instead.
+     */
     @Deprecated
     @ApiStatus.ScheduledForRemoval(inVersion = "1.2.0")
     @GroovyBlacklist
@@ -33,18 +46,38 @@ public IRegistrar getRegistrar() {
         return t::addProperty;
     }
 
+    /**
+     * Adds a property which can be accessed like a field from groovy.
+     *
+     * @param property the property to add
+     */
     public void addProperty(INamed property) {
         if (isLoaded()) {
             get().addProperty(property);
         }
     }
 
+    /**
+     * Finds all fields in a class which type is an instance of {@link INamed} and adds it as a property.
+     * If the given object is a class only static variables are used.
+     *
+     * @param o          object to find fields in
+     * @param privateToo true if private fields should be used too
+     */
     public void addPropertiesOfFields(Object o, boolean privateToo) {
         if (isLoaded()) {
             get().addPropertyFieldsOf(o, privateToo);
         }
     }
 
+    /**
+     * Creates an object mapper builder.
+     *
+     * @param name       the function name
+     * @param returnType the return type
+     * @param <V>        the return type
+     * @return a new object mapper builder
+     */
     public <V> ObjectMapper.Builder<V> objectMapperBuilder(String name, Class<V> returnType) {
         return new ObjectMapper.Builder<>(name, returnType).mod(this);
     }

src/main/java/com/cleanroommc/groovyscript/mapper/ObjectMapper.java

@@ -24,11 +24,25 @@
 import java.util.function.Function;
 import java.util.function.Supplier;
 
+/**
+ * This class handles global getter functions like `item(...)` and `fluid(...)`
+ *
+ * @param <T> return type of the function
+ */
 public class ObjectMapper<T> extends Closure<T> implements INamed, IDocumented {
 
+    /**
+     * Creates an object mapper builder.
+     * Use {@link GroovyContainer#objectMapperBuilder(String, Class)} instead!
+     *
+     * @param name       the function name
+     * @param returnType the return type
+     * @param <T>        the return type
+     * @return a new object mapper builder
+     */
     @ApiStatus.Internal
-    public static <T> Builder<T> builder(String name, Class<T> returnTpe) {
-        return new Builder<>(name, returnTpe);
+    public static <T> Builder<T> builder(String name, Class<T> returnType) {
+        return new Builder<>(name, returnType);
     }
 
     private final String name;
@@ -123,6 +137,11 @@ public List<MethodNode> getMethodNodes() {
         return methodNodes;
     }
 
+    /**
+     * A helper class to create {@link ObjectMapper}s.
+     *
+     * @param <T> the return type of the mapper
+     */
     public static class Builder<T> {
 
         private final String name;
@@ -140,22 +159,48 @@ public Builder(String name, Class<T> returnType) {
             this.returnType = returnType;
         }
 
+        /**
+         * Sets the mod who creates this mapper. This is already done when {@link GroovyContainer#objectMapperBuilder(String, Class)} is used.
+         *
+         * @param mod the creator mod
+         * @return this builder
+         * @throws IllegalStateException if GroovyScript doesn't have compat with that mod
+         */
         public Builder<T> mod(String mod) {
             return mod(ModSupport.INSTANCE.getContainer(mod));
         }
 
+        /**
+         * Sets the mod who creates this mapper. This is already done when {@link GroovyContainer#objectMapperBuilder(String, Class)} is used.
+         *
+         * @param mod the creator mod
+         * @return this builder
+         */
         public Builder<T> mod(GroovyContainer<?> mod) {
             if (this.mod == null) {
                 this.mod = mod;
             }
             return this;
         }
 
+        /**
+         * Sets the parser function. It receives a String and any amount of other arguments and returns an object of the specified type or an error.
+         *
+         * @param handler parser function
+         * @return this builder
+         */
         public Builder<T> parser(IObjectParser<T> handler) {
             this.handler = handler;
             return this;
         }
 
+        /**
+         * Sets a value completer. This is used by the LSP to provide completion for mappers.
+         * Take a look at {@link Completer}'s static methods for helpers.
+         *
+         * @param completer completer
+         * @return this builder
+         */
         public Builder<T> completer(Completer completer) {
             if (this.completer == null) {
                 this.completer = completer;
@@ -165,14 +210,34 @@ public Builder<T> completer(Completer completer) {
             return this;
         }
 
+        /**
+         * Sets a value completer. This is used by the LSP to provide completion for mappers.
+         *
+         * @param values a supplier if a list of names
+         * @return this builder
+         */
         public Builder<T> completerOfNames(Supplier<Iterable<String>> values) {
             return completer(Completer.ofNamed(values, Function.identity(), 0));
         }
 
+        /**
+         * Sets a value completer. This is used by the LSP to provide completion for mappers.
+         *
+         * @param values   a supplier if a list of objects which have names
+         * @param toString a function to turn said objects into names
+         * @return this builder
+         */
         public <V> Builder<T> completerOfNamed(Supplier<Iterable<V>> values, Function<V, String> toString) {
             return completer(Completer.ofNamed(values, toString, 0));
         }
 
+        /**
+         * Sets a value completer. This is used by the LSP to provide completion for mappers.
+         *
+         * @param values        an enum class
+         * @param caseSensitive lower case names are used if this is false
+         * @return this builder
+         */
         public <V extends Enum<V>> Builder<T> completerOfEnum(Class<V> values, boolean caseSensitive) {
             return completerOfNamed(() -> Arrays.asList(values.getEnumConstants()), s -> caseSensitive ? s.name() : s.name().toLowerCase(Locale.ROOT));
         }
@@ -185,34 +250,75 @@ public Builder<T> completer(Supplier<Iterable<ResourceLocation>> values) {
             }, 0));
         }
 
+        /**
+         * Sets a value completer. This is used by the LSP to provide completion for mappers.
+         *
+         * @param values a forge registry
+         * @return this builder
+         */
         public <V extends IForgeRegistryEntry<V>> Builder<T> completer(IForgeRegistry<V> values) {
             return completer(values::getKeys);
         }
 
+        /**
+         * Sets a default value. This is what the mapper returns when no value could be found or an error occurred. Default is null.
+         *
+         * @param defaultValue default value
+         * @return this builder
+         */
         public Builder<T> defaultValue(Supplier<T> defaultValue) {
             return defaultValueSup(() -> Result.some(defaultValue.get()));
         }
 
+        /**
+         * Sets a default value. This is what the mapper returns when no value could be found or an error occurred. Default is null.
+         *
+         * @param defaultValue default value
+         * @return this builder
+         */
         public Builder<T> defaultValueSup(Supplier<Result<T>> defaultValue) {
             this.defaultValue = defaultValue;
             return this;
         }
 
+        /**
+         * Adds a method signature. This is only used by LSP to provide helpful tooltips.
+         *
+         * @param paramTypes parameter types
+         * @return this builder
+         */
         public Builder<T> addSignature(Class<?>... paramTypes) {
             this.paramTypes.add(paramTypes);
             return this;
         }
 
+        /**
+         * Adds a documentation string. This is only used by LSP to provide helpful tooltips.
+         *
+         * @param doc documentation
+         * @return this builder
+         */
         public Builder<T> documentation(String doc) {
             this.documentation = doc;
             return this;
         }
 
+        /**
+         * Adds a documentation string. This is only used by LSP to provide helpful tooltips.
+         *
+         * @param type type of the returned objects
+         * @return this builder
+         */
         public Builder<T> docOfType(String type) {
             String mod = this.mod == null ? StringUtils.EMPTY : this.mod.getContainerName() + ' ';
             return documentation("returns a " + mod + type);
         }
 
+        /**
+         * Registers the mapper.
+         *
+         * @throws IllegalArgumentException if the mapper was misconfigured.
+         */
         public void register() {
             if (this.name == null || this.name.isEmpty()) throw new IllegalArgumentException("Name must not be empty");
             if (this.mod != null && !this.mod.isLoaded())