More validation of documenting annotations (#165)

* remove unused variable being passes * add warnings to missing doc stuff * fact check: true! * dont think that should be here * add example register() * warn as a recipe builder
CleanroomMC · Jun 16, 2024 · 21915c9 · 21915c9
1 parent 27b4452
commit 21915c9
Show file tree

Hide file tree

Showing 15 changed files with 52 additions and 27 deletions.
diff --git a/examples/postInit/pyrotech.groovy b/examples/postInit/pyrotech.groovy
@@ -188,6 +188,7 @@ mods.pyrotech.soaking_pot.recipeBuilder()
     .time(400)
     .campfireRequired(true)
     .name('diamond_to_emerald_with_amongium_soaking_pot')
+    .register()
 
 
 mods.pyrotech.soaking_pot.add('dirt_to_apple', item('minecraft:dirt'), fluid('water'), item('minecraft:apple'), 1200)

diff --git a/...cleanroommc/groovyscript/compat/mods/astralsorcery/starlightaltar/AltarRecipeBuilder.java b/...cleanroommc/groovyscript/compat/mods/astralsorcery/starlightaltar/AltarRecipeBuilder.java
@@ -249,7 +249,6 @@ public Shaped name(String name) {
             return this;
         }
 
-        @RecipeBuilderMethodDescription(field = "inputs")
         public Shaped input(ItemHandle[] inputs) {
             this.inputs = inputs;
             return this;

diff --git a/src/main/java/com/cleanroommc/groovyscript/compat/mods/betterwithmods/MillStone.java b/src/main/java/com/cleanroommc/groovyscript/compat/mods/betterwithmods/MillStone.java
@@ -110,7 +110,7 @@ public RecipeBuilder ticks(int ticks) {
             return this;
         }
 
-        @RecipeBuilderMethodDescription
+        @RecipeBuilderMethodDescription(field = "ticks")
         public RecipeBuilder time(int ticks) {
             this.ticks = ticks;
             return this;

diff --git a/src/main/java/com/cleanroommc/groovyscript/compat/mods/mekanism/Combiner.java b/src/main/java/com/cleanroommc/groovyscript/compat/mods/mekanism/Combiner.java
@@ -73,6 +73,7 @@ public static class RecipeBuilder extends AbstractRecipeBuilder<CombinerRecipe>
         @Property(defaultValue = "new ItemStack(Blocks.COBBLESTONE)")
         private ItemStack extra;
 
+        @RecipeBuilderMethodDescription
         public RecipeBuilder extra(ItemStack extra) {
             this.extra = extra;
             return this;

diff --git a/src/main/java/com/cleanroommc/groovyscript/compat/mods/mekanism/ElectrolyticSeparator.java b/src/main/java/com/cleanroommc/groovyscript/compat/mods/mekanism/ElectrolyticSeparator.java
@@ -62,6 +62,7 @@ public static class RecipeBuilder extends GasRecipeBuilder<SeparatorRecipe> {
         @Property(valid = @Comp(type = Comp.Type.GT, value = "0"))
         private double energy;
 
+        @RecipeBuilderMethodDescription
         public RecipeBuilder energy(double energy) {
             this.energy = energy;
             return this;

diff --git a/src/main/java/com/cleanroommc/groovyscript/compat/mods/mekanism/MetallurgicInfuser.java b/src/main/java/com/cleanroommc/groovyscript/compat/mods/mekanism/MetallurgicInfuser.java
@@ -88,15 +88,18 @@ public static class RecipeBuilder extends AbstractRecipeBuilder<MetallurgicInfus
         @Property(valid = @Comp(type = Comp.Type.GT, value = "0"))
         private int amount;
 
+        @RecipeBuilderMethodDescription
         public RecipeBuilder infuse(InfuseType infuse) {
             this.infuse = infuse;
             return this;
         }
 
+        @RecipeBuilderMethodDescription
         public RecipeBuilder infuse(String infuse) {
             return infuse(InfuseRegistry.get(infuse));
         }
 
+        @RecipeBuilderMethodDescription
         public RecipeBuilder amount(int amount) {
             this.amount = amount;
             return this;

diff --git a/...in/java/com/cleanroommc/groovyscript/compat/mods/mekanism/PressurizedReactionChamber.java b/...in/java/com/cleanroommc/groovyscript/compat/mods/mekanism/PressurizedReactionChamber.java
@@ -77,11 +77,13 @@ public static class RecipeBuilder extends GasRecipeBuilder<PressurizedRecipe> {
         @Property(valid = @Comp(type = Comp.Type.GT, value = "0"))
         private double energy;
 
+        @RecipeBuilderMethodDescription
         public RecipeBuilder duration(int duration) {
             this.duration = duration;
             return this;
         }
 
+        @RecipeBuilderMethodDescription
         public RecipeBuilder energy(double energy) {
             this.energy = energy;
             return this;

diff --git a/src/main/java/com/cleanroommc/groovyscript/compat/mods/mekanism/Sawmill.java b/src/main/java/com/cleanroommc/groovyscript/compat/mods/mekanism/Sawmill.java
@@ -91,11 +91,13 @@ public static class RecipeBuilder extends AbstractRecipeBuilder<SawmillRecipe> {
         @Property(defaultValue = "1.0", valid = {@Comp(type = Comp.Type.GTE, value = "0"), @Comp(type = Comp.Type.LTE, value = "1")})
         private double chance = 1.0;
 
+        @RecipeBuilderMethodDescription
         public RecipeBuilder extra(ItemStack extra) {
             this.extra = extra;
             return this;
         }
 
+        @RecipeBuilderMethodDescription
         public RecipeBuilder chance(double chance) {
             this.chance = chance;
             return this;

diff --git a/src/main/java/com/cleanroommc/groovyscript/compat/mods/pyrotech/ChoppingBlock.java b/src/main/java/com/cleanroommc/groovyscript/compat/mods/pyrotech/ChoppingBlock.java
@@ -63,9 +63,10 @@ public static class RecipeBuilder extends AbstractRecipeBuilder<ChoppingBlockRec
 
         @Property
         private final IntList chops = new IntArrayList();
+        @Property
         private final IntList quantities = new IntArrayList();
 
-        @RecipeBuilderMethodDescription(field = "chops, quantities")
+        @RecipeBuilderMethodDescription(field = {"chops", "quantities"})
         public RecipeBuilder chops(int chops, int quantities) {
             this.chops.add(chops);
             this.quantities.add(quantities);

diff --git a/src/main/java/com/cleanroommc/groovyscript/compat/mods/pyrotech/SoakingPot.java b/src/main/java/com/cleanroommc/groovyscript/compat/mods/pyrotech/SoakingPot.java
@@ -103,6 +103,7 @@ public void validate(GroovyLog.Msg msg) {
         }
 
         @Override
+        @RecipeBuilderRegistrationMethod
         public @Nullable SoakingPotRecipe register() {
             if (!validate()) return null;
             SoakingPotRecipe recipe = new SoakingPotRecipe(output.get(0), input.get(0).toMcIngredient(), fluidInput.get(0), campfireRequired, time).setRegistryName(name);

diff --git a/src/main/java/com/cleanroommc/groovyscript/compat/mods/rustic/Alchemy.java b/src/main/java/com/cleanroommc/groovyscript/compat/mods/rustic/Alchemy.java
@@ -100,7 +100,7 @@ public static class RecipeBuilder extends AbstractRecipeBuilder<ICondenserRecipe
         @Property
         private boolean advanced;
 
-        @RecipeBuilderMethodDescription
+        @RecipeBuilderMethodDescription(field = "output")
         public RecipeBuilder effect(PotionEffect effect) {
             var output = new ItemStack(ModItems.ELIXIR);
             ElixirUtils.addEffect(effect, output);

diff --git a/src/main/java/com/cleanroommc/groovyscript/documentation/Builder.java b/src/main/java/com/cleanroommc/groovyscript/documentation/Builder.java
@@ -2,8 +2,6 @@
 
 import com.cleanroommc.groovyscript.api.GroovyLog;
 import com.cleanroommc.groovyscript.api.documentation.annotations.*;
-import com.cleanroommc.groovyscript.compat.mods.GroovyContainer;
-import com.cleanroommc.groovyscript.compat.mods.GroovyPropertyContainer;
 import com.google.common.collect.ComparisonChain;
 import it.unimi.dsi.fastutil.chars.Char2CharArrayMap;
 import it.unimi.dsi.fastutil.chars.Char2CharMap;
@@ -29,16 +27,14 @@ public class Builder {
         defaultReturnValue(Character.MIN_VALUE);
     }};
 
-    private final GroovyContainer<? extends GroovyPropertyContainer> mod;
     private final String reference;
     private final Method builderMethod;
     private final RecipeBuilderDescription annotation;
     private final Map<String, FieldDocumentation> fields;
     private final Map<String, List<RecipeBuilderMethod>> methods;
     private final List<Method> registrationMethods;
 
-    public Builder(GroovyContainer<? extends GroovyPropertyContainer> mod, Method builderMethod, String reference, String baseTranslationKey) {
-        this.mod = mod;
+    public Builder(Method builderMethod, String reference, String baseTranslationKey) {
         this.builderMethod = builderMethod;
         this.reference = reference;
         this.annotation = builderMethod.getAnnotation(RecipeBuilderDescription.class);
@@ -242,6 +238,35 @@ public List<String> annotations() {
     public String documentMethods() {
         StringBuilder out = new StringBuilder();
 
+        methods.keySet().forEach(target -> {
+            if (fields.containsKey(target)) return;
+            GroovyLog.get().warn("Couldn't find field '{}' referenced in a method used for recipe builder '{}'", target, reference);
+        });
+
+        if (fields.values().stream().anyMatch(FieldDocumentation::isUsed)) {
+            out.append(documentFields());
+        } else {
+            GroovyLog.get().warn("Couldn't find any fields being used for recipe builder '{}'", reference);
+        }
+
+        if (registrationMethods.isEmpty()) {
+            GroovyLog.get().warn("Couldn't find any registration methods for recipe builder '{}'", reference);
+        } else {
+            for (Method registerMethod : registrationMethods) {
+                out.append("- ");
+                String returnType = registerMethod.getAnnotatedReturnType().getType().getTypeName();
+                if ("void".equals(returnType) || "null".equals(returnType)) out.append(I18n.format("groovyscript.wiki.register"));
+                else out.append(I18n.format("groovyscript.wiki.register_return", returnType));
+                out.append("\n\n");
+                out.append(new CodeBlockBuilder().line(String.format("%s()", registerMethod.getName())).indentation(1).toString());
+            }
+        }
+
+        return out.toString();
+    }
+
+    public StringBuilder documentFields() {
+        StringBuilder out = new StringBuilder();
         fields.values().stream()
                 .sorted()
                 .filter(FieldDocumentation::isUsed)
@@ -266,7 +291,7 @@ public String documentMethods() {
                     List<RecipeBuilderMethod> recipeBuilderMethods = methods.get(fieldDocumentation.getField().getName());
 
                     if (recipeBuilderMethods == null || recipeBuilderMethods.isEmpty()) {
-                        GroovyLog.get().debug("Couldn't find any recipe builder methods for {} in {}", fieldDocumentation.getField().getName(), reference);
+                        GroovyLog.get().warn("Couldn't find any methods targeting field '{}' in recipe builder '{}'", fieldDocumentation.getField().getName(), reference);
                     } else {
                         out.append(new CodeBlockBuilder()
                                            .line(recipeBuilderMethods.stream()
@@ -278,17 +303,7 @@ public String documentMethods() {
                                            .toString());
                     }
                 });
-
-        for (Method registerMethod : registrationMethods) {
-            out.append("- ");
-            String returnType = registerMethod.getAnnotatedReturnType().getType().getTypeName();
-            if ("void".equals(returnType) || "null".equals(returnType)) out.append(I18n.format("groovyscript.wiki.register"));
-            else out.append(I18n.format("groovyscript.wiki.register_return", returnType));
-            out.append("\n\n");
-            out.append(new CodeBlockBuilder().line(String.format("%s()", registerMethod.getName())).indentation(1).toString());
-        }
-
-        return out.toString();
+        return out;
     }
 
     private String createBuilder(Example example) {
@@ -304,8 +319,7 @@ private String createBuilder(Example example) {
 
         out.append(String.join("", getOutputs(generateParts(example.value()))));
 
-        if (registrationMethods.isEmpty()) GroovyLog.get().debug("Couldn't find any registration methods for {}", builderMethod.getName());
-        else out.append("    .").append(String.format("%s()", registrationMethods.get(0).getName()));
+        if (!registrationMethods.isEmpty()) out.append("    .").append(String.format("%s()", registrationMethods.get(0).getName()));
 
         if (example.commented()) out.append("*/");
 

diff --git a/src/main/java/com/cleanroommc/groovyscript/documentation/Registry.java b/src/main/java/com/cleanroommc/groovyscript/documentation/Registry.java
@@ -2,7 +2,6 @@
 
 import com.cleanroommc.groovyscript.api.GroovyBlacklist;
 import com.cleanroommc.groovyscript.api.INamed;
-import com.cleanroommc.groovyscript.api.IScriptReloadable;
 import com.cleanroommc.groovyscript.api.documentation.annotations.*;
 import com.cleanroommc.groovyscript.compat.mods.GroovyContainer;
 import com.cleanroommc.groovyscript.compat.mods.GroovyPropertyContainer;
@@ -122,7 +121,7 @@ public String exampleBlock() {
         out.append("// ").append(getTitle()).append(":").append("\n");
         out.append("// ").append(WordUtils.wrap(getDescription(), Documentation.MAX_LINE_LENGTH, "\n// ", false)).append("\n\n");
         out.append(documentMethodDescriptionType(MethodDescription.Type.REMOVAL));
-        for (Method method : recipeBuilderMethods) out.append(new Builder(mod, method, reference, baseTranslationKey).builderExampleFile()).append("\n");
+        for (Method method : recipeBuilderMethods) out.append(new Builder(method, reference, baseTranslationKey).builderExampleFile()).append("\n");
         if (!recipeBuilderMethods.isEmpty()) out.append("\n");
         out.append(documentMethodDescriptionType(MethodDescription.Type.ADDITION));
         out.append(documentMethodDescriptionType(MethodDescription.Type.VALUE));
@@ -207,7 +206,7 @@ private String recipeBuilder() {
                 .append(I18n.format("groovyscript.wiki.recipe_builder_note", Documentation.DEFAULT_FORMAT.linkToBuilder())).append("\n\n");
 
         for (int i = 0; i < recipeBuilderMethods.size(); i++) {
-            Builder builder = new Builder(mod, recipeBuilderMethods.get(i), reference, baseTranslationKey);
+            Builder builder = new Builder(recipeBuilderMethods.get(i), reference, baseTranslationKey);
             out.append(new AdmonitionBuilder()
                                .type(Admonition.Type.ABSTRACT)
                                .hasTitle(true)

diff --git a/src/main/java/com/cleanroommc/groovyscript/registry/AbstractCraftingRecipeBuilder.java b/src/main/java/com/cleanroommc/groovyscript/registry/AbstractCraftingRecipeBuilder.java
@@ -95,7 +95,7 @@ public AbstractCraftingRecipeBuilder<R> replace() {
         return this;
     }
 
-    @RecipeBuilderMethodDescription
+    @RecipeBuilderMethodDescription(field = "replace")
     public AbstractCraftingRecipeBuilder<R> replaceByName() {
         this.replace = 2;
         return this;

diff --git a/src/main/resources/assets/groovyscript/lang/en_us.lang b/src/main/resources/assets/groovyscript/lang/en_us.lang
@@ -1801,6 +1801,7 @@ groovyscript.wiki.pyrotech.campfire.add=Adds recipes in the format `name`, `inpu
 groovyscript.wiki.pyrotech.chopping_block.title=Chopping Block
 groovyscript.wiki.pyrotech.chopping_block.description=When using a axe it can convert items
 groovyscript.wiki.pyrotech.chopping_block.chops.value=Sets how often the item needs to be hit with output amount. Call it 4 times for 4 different tiers (Crude, Stone, Iron, Diamond)
+groovyscript.wiki.pyrotech.chopping_block.quantities.value=Sets the amount of items output for a given tier. Call it 4 times for 4 different tiers (Crude, Stone, Iron, Diamond)
 
 groovyscript.wiki.pyrotech.compacting_bin.title=Compacting Bin
 groovyscript.wiki.pyrotech.compacting_bin.description=When using a shovel it can convert items