Document new and deprecated methods, catch exceptions

src/main/java/carpet/script/annotation/SimpleTypeConverter.java

@@ -25,6 +25,7 @@ import carpet.script.value.ValueConversions;
  * <p>{@link SimpleTypeConverter}s are reused whenever asked for one, since they don't have any complexity.</p>
  *
  * @see #registerType(Class, Class, Function, String)
+ * @see #registerType(Class, Class, BiFunction, String)
  * 
  * @param <T> The type of the required input {@link Value}
  * @param <R> The type that this converter converts to
@@ -52,14 +53,29 @@ public final class SimpleTypeConverter<T extends Value, R> implements ValueConve
     private final String typeName;
 
     /**
-     * <p>The default constructor for {@link SimpleTypeConverter}.</p>
+     * Same as {@link #SimpleTypeConverter(Class, BiFunction, String)}, but without the converter function taking a {@link Context}
+     * 
+     * @param inputType The required type for the input {@link Value}
+     * @param converter The function to convert an instance of inputType into R, with the context of the call.
+     * @param typeName  The name of the type for error messages
+     * 
+     * @see #SimpleTypeConverter(Class, BiFunction, String)
+     */
+    public SimpleTypeConverter(final Class<T> inputType, final Function<T, R> converter, final String typeName)
+    {
+        this(inputType, (v, c) -> converter.apply(v), typeName);
+    }
+
+    /**
+     * <p>A constructor for {@link SimpleTypeConverter}.</p>
      * 
      * <p>This is public in order to provide an implementation to use when registering {@link ValueConverter}s for the {@link Param.Strict} annotation
      * registry, and it's not intended way to register new {@link SimpleTypeConverter}</p> <p>Use {@link #registerType(Class, Class, Function, String)} for
      * that.</p>
      * 
      * @param inputType The required type for the input {@link Value}
-     * @param converter The function to convert an instance of inputType into R.
+     * @param converter The function to convert an instance of inputType into R, with the context of the call.
+     * @param typeName  The name of the type for error messages
      */
     public SimpleTypeConverter(final Class<T> inputType, final BiFunction<T, Context, R> converter, final String typeName)
     {
@@ -69,14 +85,6 @@ public final class SimpleTypeConverter<T extends Value, R> implements ValueConve
         this.typeName = typeName;
     }
 
-    public SimpleTypeConverter(final Class<T> inputType, final Function<T, R> converter, final String typeName)
-    {
-        super();
-        this.converter = (v, c) -> converter.apply(v);
-        this.valueClass = inputType;
-        this.typeName = typeName;
-    }
-
     @Override
     public String getTypeName()
     {
@@ -114,6 +122,26 @@ public final class SimpleTypeConverter<T extends Value, R> implements ValueConve
      *                  when given {@link Value} cannot be converted to the {@code <R>}, to follow the {@link ValueConverter} contract, but it
      *                  can also throw an {@link InternalExpressionException} by itself if really necessary.
      * @param typeName The name of the type, following the conventions of {@link ValueConverter#getTypeName()}
+     * 
+     * @see #registerType(Class, Class, BiFunction, String)
+     */
+    public static <T extends Value, R> void registerType(final Class<T> requiredInputType, final Class<R> outputType,
+                                                         final Function<T, R> converter, final String typeName)
+    {
+        registerType(requiredInputType, outputType, (val, ctx) -> converter.apply(val), typeName);
+    }
+
+    /**
+     * <p>Registers a new conversion from a {@link Value} subclass to a Java type, with the context of the call.</p>
+     * 
+     * @param <T> The {@link Value} subtype required for this conversion, for automatic checked casting
+     * @param <R> The type of the resulting object
+     * @param requiredInputType The {@link Class} of {@code <T>}
+     * @param outputType The {@link Class} of {@code <R>>}
+     * @param converter A function that converts from the given {@link Value} subtype to the given type. Should ideally return {@code null}
+     *                  when given {@link Value} cannot be converted to the {@code <R>}, to follow the {@link ValueConverter} contract, but it
+     *                  can also throw an {@link InternalExpressionException} by itself if really necessary.
+     * @param typeName The name of the type, following the conventions of {@link ValueConverter#getTypeName()}
      */
     public static <T extends Value, R> void registerType(final Class<T> requiredInputType, final Class<R> outputType,
                                                          final BiFunction<T, Context, R> converter, final String typeName)
@@ -121,10 +149,4 @@ public final class SimpleTypeConverter<T extends Value, R> implements ValueConve
         final SimpleTypeConverter<T, R> type = new SimpleTypeConverter<>(requiredInputType, converter, typeName);
         byResult.put(outputType, type);
     }
-
-    public static <T extends Value, R> void registerType(final Class<T> requiredInputType, final Class<R> outputType,
-                                                         final Function<T, R> converter, final String typeName)
-    {
-        registerType(requiredInputType, outputType, (val, ctx) -> converter.apply(val), typeName);
-    }
 }

src/main/java/carpet/script/annotation/ValueConverter.java

@@ -50,7 +50,7 @@ public interface ValueConverter<R>
      * trying to convert to anything else, where it would be recommended to tell the user the name of the final type instead.</p>
      * 
      * @param value   The {@link Value} to convert
-     * @param context
+     * @param context The {@link Context} of the call
      * @return The converted value, or {@code null} if the conversion failed in the process
      * @apiNote <p>While most implementations of this method should and will return the type from this method, implementations that <b>require</b>
      *          parameters from {@link #checkAndConvert(Iterator, Context, Context.Type)} or that require multiple parameters may decide to throw
@@ -65,11 +65,28 @@ public interface ValueConverter<R>
      */
     @Nullable R convert(Value value, final Context context);
 
+    /**
+     * Old version of {@link #convert(Value)} without taking a {@link Context}.<p>
+     * 
+     * This shouldn't be used given converters now take a context in the convert function to allow for converting
+     * values in lists or other places without using static state.<p>
+     * 
+     * @param value The value to convert
+     * @return A converted value
+     * @deprecated Calling this method instead of {@link #convert(Value, Context)} may not return values for some converters
+     */
     @Deprecated(forRemoval = true)
     default R convert(final Value value)
+    {
+        try
         {
             return convert(value, null);
         }
+        catch (NullPointerException e)
+        {
+            return null;
+        }
+    }
 
     /**
      * <p>Returns whether this {@link ValueConverter} consumes a variable number of elements from the {@link Iterator} passed to it via
@@ -185,8 +202,7 @@ public interface ValueConverter<R>
      *           they may consume variable arguments, implement {@link #consumesVariableArgs()}</p> <p>This method holds the same nullability
      *           constraints as {@link #convert(Value, Context)}</p>
      * @param valueIterator An {@link Iterator} holding the {@link Value} to convert in next position
-     * @param context       The {@link Context} this function has been called with. This was used when this passed lazy values instead in order to
-     *                      evaluate, now it's used to get the context
+     * @param context       The {@link Context} this function has been called with
      * @param contextType   The {@link Context.Type} that the original function was called with
      * @return The next {@link Value} (s) converted to the type {@code <R>} of this {@link ValueConverter}
      * @implNote This method's default implementation runs the {@link #convert(Value, Context)} function in the next {@link Value} ignoring {@link Context} and