Document via Descriptor and adjust Recipe Builder (#302)

* add method to generate based on descriptor

* apply MethodOverride

* adjust import sort order

* extract noise from Documentation

* shorten Predicate line

* extract Exporter.signature code and rename

* minor cleanup and simplification

* apply override capability to builder

* apply RecipeBuilderOverride

* fix dissolver not overriding parent

* replace duplicate list with name to signature map

* add title and description to RBD

* apply custom builder titles and descriptions

* fix format being used oddly

* fix Miniaturization duration method

* fix dissolver using output

* fix typo with roots predicates

* fix fountain using duplicate lang keys

* move descriptor helper and extract inner class

* create ComparisonHelper and apply

* log skipped classes as debug

* remove getName from MethodAnnotation

* rework how skipped classes are logged

* move helper classes into specific folder

* format doesnt get used there

* fix minor typos

* ensure slash in link generators

* suppress invalid string buffer warnings

* adjust description helper

* extract and fix defaultValueConverter

* default value for longs have L

* improve javadoc localization key examples

* update example docs

Author: WaitingIdly

examples/postInit/roots.groovy

@@ -208,8 +208,8 @@ mods.roots.pacifist.recipeBuilder()
 
 
 // Predicates:
-// Predicates are used in Transmution and RunicShearBlock. They either match all blockstates of a block, or all blockstates
-// that have the given properties that match the input blockstate.
+// Predicates are used in Transmutation and RunicShearBlock. They either match all blockstates of a block, or all
+// blockstates that have the given properties that match the input blockstate.
 
 mods.roots.predicates.stateBuilder()
     .blockstate(blockstate('minecraft:red_flower'))

src/main/java/com/cleanroommc/groovyscript/api/documentation/annotations/Admonition.java

@@ -18,7 +18,7 @@
      * The localization key for the admonition description, should be in the format of
      * <br>
      * <code>
-     * groovyscript.wiki.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() VirtualizedRegistry#getName()}.note{index of note in array}
+     * groovyscript.wiki.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() {name}}.note{index}
      * </code>
      *
      * @return localization key for the admonition description

src/main/java/com/cleanroommc/groovyscript/api/documentation/annotations/Example.java

@@ -27,10 +27,15 @@
 public @interface Example {
 
     /**
-     * For recipe builders, this will be a string that is a valid one-line series of methods to create a Recipe Builder that will
+     * For basic recipe builders, this will be a string that is a valid one-line series of methods to create a Recipe Builder that will
      * pass the {@link com.cleanroommc.groovyscript.helper.recipe.IRecipeBuilder#validate() IRecipeBuilder#validate()} check and be successfully registered.
-     * <br>
-     * For methods, this should be exclusive the parameters of the method. e.g. {@code "item('minecraft:clay')"}<br>
+     * {@code ".do('thing').and('other')"}
+     * <p>
+     * For complex recipe builders, those that have one or more parameters, in the creation method,
+     * the above is true after an initial segment for the creation. {@code "('init').do('thing').and('other')"}
+     * <p>
+     * For methods, this should be exclusive the parameters of the method. e.g. {@code "item('minecraft:clay')"}
+     * <p>
      * Any comments for the wiki should be marked by
      * <code>
      * /*()*{@literal /}

src/main/java/com/cleanroommc/groovyscript/api/documentation/annotations/MethodDescription.java

@@ -11,9 +11,15 @@
  * All fields are optional, and most have default values generated in {@link Example}.
  *
  * <ul>
+ *     <li>{@link #method()} either contains nothing if annotated on a method or contains a
+ *     string that targets the desired method in conjunction with {@link MethodOverride}.
+ *     To target a method, if only a single method has the given name, excluding
+ *     bridge, non-public, Object, or methods annotated with {@link com.cleanroommc.groovyscript.api.GroovyBlacklist},
+ *     the target may be the method name.
+ *     Otherwise, the target must be the name and full descriptor of the method.</li>
  *     <li>{@link #description()} is a localization key that is autogenerated to be
  *     <code>
- *         groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() GroovyContainer#getModId()}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() VirtualizedRegistry#getName()}.{@link Method#getName()}
+ *         groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() {modId}}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() {name}}.{@link Method#getName() {methodName}}
  *     </code>
  *     </li>
  *     <li>{@link #example()} is an array of {@link Example}s In situations where either a single {@link Example} with multiple lines or
@@ -28,16 +34,32 @@
 @Target(ElementType.METHOD)
 public @interface MethodDescription {
 
+    /**
+     * If this {@link MethodDescription} annotation is attached to a method, this element is set to the name of the method they are attached to.
+     * When annotated on a method directly, this should not be set, as it has no functionality.
+     * <br>
+     * If this is not annotated to a method, this should either be the method name
+     * (if only a single method has the given name)
+     * or needs to be the name and full descriptor of the method.
+     * <br>
+     * Methods that are bridge, non-public, Object, or methods annotated with {@link com.cleanroommc.groovyscript.api.GroovyBlacklist}
+     * cannot be targeted.
+     *
+     * @return the target method, if not annotated to a method directly.
+     * @see MethodOverride
+     */
+    String method() default "";
+
     /**
      * The localization key for a description of the compat.
      * <br>
      * Generates a description via minecraft's localization files via
      * <code>{@link net.minecraft.client.resources.I18n#format(String, Object...) I18n.format(description())}</code>
      * <br>
      * If this is empty, will fall back to generating a description based on
-     * <code>groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() GroovyContainer#getModId()}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() VirtualizedRegistry#getName()}.{@link Method#getName()}</code>.
+     * <code>groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() {modId}}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() {name}}.{@link Method#getName() {methodName}}</code>.
      * Then, if that does not have a lang key defined, it will attempt to use a global lang key based on the method name
-     * <code>groovyscript.wiki.{@link Method#getName()}</code>
+     * <code>groovyscript.wiki.{@link Method#getName() {methodName}}</code>
      * if that also does not have a lang key defined, will log a missing key in the {@code groovy.log} file.
      *
      * @return localization key for method description

src/main/java/com/cleanroommc/groovyscript/api/documentation/annotations/MethodOverride.java

@@ -0,0 +1,39 @@
+package com.cleanroommc.groovyscript.api.documentation.annotations;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Allows a {@link RegistryDescription} to override any
+ * {@link MethodDescription} or {@link RecipeBuilderDescription} declarations.
+ * <p>
+ * Methods can be referred to by name if there is only one method with the given name
+ * in the class, otherwise must be referred to by the method name + method signature.
+ * <p>
+ * While this can be used for any method, it is preferred to only use it for
+ * methods that require it - namely, methods that are declared in a parent class
+ * and not overridden in the focused class.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({}) // No targets allowed
+public @interface MethodOverride {
+
+    /**
+     * An override to other {@link MethodDescription} declarations, and only used for {@link MethodDescription} instances which
+     * should have custom data for the class they are accessed from.
+     *
+     * @return array of method description annotations for the class
+     * @see MethodDescription
+     */
+    MethodDescription[] method() default {};
+
+    /**
+     * An override to other {@link RecipeBuilderDescription} declarations, and only used for {@link RecipeBuilderDescription} instances which
+     * should have custom data for the class they are accessed from.
+     *
+     * @return array of method description annotations for the class
+     * @see RecipeBuilderDescription
+     */
+    RecipeBuilderDescription[] recipeBuilder() default {};
+}

src/main/java/com/cleanroommc/groovyscript/api/documentation/annotations/Property.java

@@ -16,15 +16,15 @@
  *     </li>
  *     <li>
  *         {@link ElementType#METHOD}: Marks the field targeted by {@link #property()} within the class the attached method returns with this {@link Property}.
- *         Can only be attached via being inside {@link RecipeBuilderDescription#requirement()}.
+ *         Can be attached via being inside {@link RecipeBuilderOverride#requirement()}.
  *     </li>
  * </ul>
  * <p>
  * Elements:
  * <ul>
  *     <li>{@link #value()} is a localization key that is autogenerated to be
  *     <code>
- *         groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() GroovyContainer#getModId()}.{@link Field#getName()}.value
+ *         groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() {modId}}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() {name}}.{@link Field#getName() {fieldName}}.value
  *     </code>
  *     and states what the property does.
  *     </li>
@@ -53,7 +53,7 @@
     /**
      * The localization key for the name of the compat, will default to generating
      * <code>
-     * groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() GroovyContainer#getModId()}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() VirtualizedRegistry#getName()}.{@link Field#getName()}.value
+     * groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() {modId}}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() {name}}.{@link Field#getName() {fieldName}}.value
      * </code>
      *
      * @return localization key for what the target field will accomplish
@@ -219,7 +219,7 @@
      * Wrapper to allow repeatable instances of {@link Property}.
      * If more than one {@link Property} is applied to anywhere other than a class, it will generate an error.
      * For a given Field. only a single {@link Property} should be attached,
-     * and for a given Method, all {@link Property} annotations should be placed inside {@link RecipeBuilderDescription#requirement()}
+     * and for a given Method, all {@link Property} annotations should be placed inside {@link RecipeBuilderOverride#requirement()}
      *
      * @see Property
      */

src/main/java/com/cleanroommc/groovyscript/api/documentation/annotations/RecipeBuilderDescription.java

@@ -4,28 +4,101 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
-import java.lang.reflect.Field;
+import java.lang.reflect.Method;
 
 /**
  * Marks the given Method as the initializing method for a Recipe Builder, indicating it returns a Recipe Builder class.<br>
  * A Recipe Builder is a class which follows the Builder design pattern, where each step of the builder returns the builder class,
  * allowing chaining of methods to quickly and cleanly create complicated objects which may or may not require some values.
  *
  * <ul>
- *     <li>{@link #example()} is an array of {@link Example}s In situations where either a single {@link Example} with multiple lines or
- *     multiple {@link Example}s could be used, using multiple {@link Example}s is preferable.</li>
- *     <li>{@link #requirement()} is a localization key that is autogenerated to be
+ *     <li>{@link #title()} is a localization key that is autogenerated to be
  *     <code>
- *         groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() GroovyContainer#getModId()}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() VirtualizedRegistry#getName()}.{@link Field#getName()}
+ *         groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() {modId}}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() {name}}.{@link Method#getName() {methodName}}.title
  *     </code>
+ *     to name the Recipe Builder.
  *     </li>
+ *     <li>{@link #description()} is a localization key that is autogenerated to be
+ *     <code>
+ *         groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() {modId}}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() {name}}.{@link Method#getName() {methodName}}.description
+ *     </code>
+ *     to describe the method used to create the Recipe Builder.
+ *     </li>
+ *     <li>{@link #method()} either contains nothing if annotated on a method or contains a
+ *     string that targets the desired method in conjunction with {@link MethodOverride}.
+ *     To target a method, if only a single method has the given name, excluding
+ *     bridge, non-public, Object, or methods annotated with {@link com.cleanroommc.groovyscript.api.GroovyBlacklist},
+ *     the target may be the method name.
+ *     Otherwise, the target must be the name and full descriptor of the method.</li>
+ *     <li>{@link #clazz()} is the class being targeted by the recipe builder. By default this is the return value of the method.</li>
+ *     <li>{@link #example()} is an array of {@link Example}s In situations where either a single {@link Example} with multiple lines or
+ *     multiple {@link Example}s could be used, using multiple {@link Example}s is preferable.</li>
+ *     <li>{@link #override()} allows creating overrides for the {@link Property}, {@link RecipeBuilderMethodDescription}, and {@link RecipeBuilderRegistrationMethod}
+ *     annotated in the builder using {@link RecipeBuilderOverride}.</li>
  *     <li>{@link #priority()} is an integer that influences the sorting of the {@link RecipeBuilderDescription} relative to other {@link RecipeBuilderDescription}s.</li>
  * </ul>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface RecipeBuilderDescription {
 
+    /**
+     * The localization key for the name of the builder, if different from Recipe Builder.
+     * <br>
+     * This should be used when there is more than one way to create a Recipe Builder
+     * for the given class.
+     * <br>
+     * Generates the title via minecraft's localization files via
+     * <code>{@link net.minecraft.client.resources.I18n#format(String, Object...) I18n.format(description())}</code>
+     * <br>
+     * If this is empty, will fall back to generating a description based on
+     * <code>groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() {modId}}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() {name}}.{@link Method#getName() {methodName}}.title</code>.
+     * Then, if that does not have a lang key defined, it will use the global default for recipe builders of
+     * <code>groovyscript.wiki.recipe_builder.title</code>.
+     *
+     * @return localization key for method title
+     */
+    String title() default "";
+
+    /**
+     * The localization key for a description of the compat.
+     * <br>
+     * This should always be used when the creation method accepts parameters.
+     * In most cases this should be changed so that each parameter is an individual builder method,
+     * but in some situations this is not possible, and so must be documented accordingly.
+     * <br>
+     * When a builder method with one or more parameters does not have a localization key set,
+     * if it does not use a lang key, it will log a missing key in the {@code groovy.log} file.
+     * <br>
+     * Generates a description via minecraft's localization files via
+     * <code>{@link net.minecraft.client.resources.I18n#format(String, Object...) I18n.format(description())}</code>
+     * <br>
+     * If this is empty, will fall back to generating a description based on
+     * <code>groovyscript.wiki.{@link com.cleanroommc.groovyscript.compat.mods.GroovyContainer#getModId() {modId}}.{@link com.cleanroommc.groovyscript.registry.VirtualizedRegistry#getName() {name}}.{@link Method#getName() {methodName}}.description</code>.
+     * Then, if that does not have a lang key defined, it will use the global default for recipe builders of
+     * <code>groovyscript.wiki.recipe_builder.description</code>.
+     *
+     * @return localization key for method description
+     */
+    String description() default "";
+
+    /**
+     * If this {@link RecipeBuilderDescription} annotation is attached to a method, this element is set to the name of the method they are attached to.
+     * When annotated on a method directly, this should not be set, as it has no functionality.
+     *
+     * @return the target method, if not annotated to a method directly.
+     * @see MethodOverride
+     */
+    String method() default "";
+
+    /**
+     * The builder class. By default, this will use the return class of the target method.
+     * If this is undesired, specify the real class here.
+     *
+     * @return the class used by the builder, if different from the return type of the target method
+     */
+    Class<?> clazz() default void.class;
+
     /**
      * An array of examples, which will then be formatted and generated for both the wiki and the text script files.
      *
@@ -40,9 +113,24 @@
      *
      * @return array of requirements unique to the recipe builder being accessed via this method
      * @see Property
+     * @deprecated use {@link #override()} and {@link RecipeBuilderOverride#requirement()}
      */
+    @Deprecated
     Property[] requirement() default {};
 
+    /**
+     * Allows overriding the {@link Property}, {@link RecipeBuilderMethodDescription}, and {@link RecipeBuilderRegistrationMethod} annotations
+     * for the builder class.
+     * This should only be used in situations where custom data that does not apply to the class normally
+     * is used.
+     *
+     * @return overrides for the Recipe Builder annotations
+     * @see Property
+     * @see RecipeBuilderMethodDescription
+     * @see RecipeBuilderRegistrationMethod
+     */
+    RecipeBuilderOverride override() default @RecipeBuilderOverride;
+
     /**
      * Priority of the method, relative to other Recipe Builder methods in the same class.
      * Priorities sort entries such that lowest is first, with ties being broken via alphabetical sorting of the method name.