PR feedback

Author: robin-aws

smithy-jmespath/src/main/java/software/amazon/smithy/jmespath/JmespathExceptionType.java

@@ -4,20 +4,47 @@
  */
 package software.amazon.smithy.jmespath;
 
+/**
+ * Defines categories of JMESPath errors.
+ * A superset of the types defined in <a href="https://jmespath.org/specification.html#errors">the specification.
+ */
 public enum JmespathExceptionType {
+    /**
+     * The "syntax" class of JMESPath errors.
+     * <p>
+     * "syntax" is not listed in the specification, but it is used
+     * in <a href="https://github.com/jmespath/jmespath.test">the compliance tests</a> to indicate invalid expressions.
+     */
     SYNTAX,
+
+    /**
+     * The "invalid-type" class of JMESPath errors.
+     */
     INVALID_TYPE,
+
+    /**
+     * The "invalid-value" class of JMESPath errors.
+     */
     INVALID_VALUE,
+
+    /**
+     * The "unknown-function" class of JMESPath errors.
+     */
     UNKNOWN_FUNCTION,
+
+    /**
+     * The "invalid-arity" class of JMESPath errors.
+     */
     INVALID_ARITY,
+
+    /**
+     * Any other error cause.
+     */
     OTHER;
 
     /**
      * Returns the corresponding enum value for one of the identifiers used in
      * <a href="https://jmespath.org/specification.html#errors">the JMESPath specification</a>.
-     * <p>
-     * "syntax" is not listed in the specification, but it is used
-     * in <a href="https://github.com/jmespath/jmespath.test">the compliance tests</a> to indicate invalid expressions.
      */
     public static JmespathExceptionType fromID(String id) {
         return valueOf(id.toUpperCase().replace('-', '_'));

smithy-jmespath/src/main/java/software/amazon/smithy/jmespath/JmespathExpression.java

@@ -116,7 +116,7 @@ public LinterResult lint(LiteralExpression currentNode) {
      * @return Returns the result of evaluating the expression.
      */
     public LiteralExpression evaluate(LiteralExpression currentNode) {
-        return evaluate(currentNode, new LiteralExpressionJmespathRuntime());
+        return evaluate(currentNode, LiteralExpressionJmespathRuntime.INSTANCE);
     }
 
     /**

smithy-jmespath/src/main/java/software/amazon/smithy/jmespath/LiteralExpressionJmespathRuntime.java

@@ -14,6 +14,12 @@
 import software.amazon.smithy.jmespath.evaluation.MappingIterable;
 import software.amazon.smithy.jmespath.evaluation.NumberType;
 
+/**
+ * A singleton implementation of the JmespathRuntime interface based on instances of the LiteralExpression class.
+ * <p>
+ * Does not use values of the additional LiteralExpression.EXPREF or LiteralExpression.ANY types
+ * as they aren't necessary.
+ */
 public final class LiteralExpressionJmespathRuntime implements JmespathRuntime<LiteralExpression> {
 
     public static final LiteralExpressionJmespathRuntime INSTANCE = new LiteralExpressionJmespathRuntime();

smithy-jmespath/src/main/java/software/amazon/smithy/jmespath/evaluation/EvaluationUtils.java

@@ -10,6 +10,9 @@
 import java.util.Objects;
 import software.amazon.smithy.jmespath.RuntimeType;
 
+/**
+ * Functions that make evaluating JmespathExpressions or implementing the JmespathRuntime interface easier.
+ */
 public final class EvaluationUtils {
 
     private static final InheritingClassMap<NumberType> numberTypeForClass = InheritingClassMap.<NumberType>builder()

smithy-jmespath/src/main/java/software/amazon/smithy/jmespath/evaluation/JmespathRuntime.java

@@ -116,6 +116,7 @@ default String toString(T value) {
                     if (first) {
                         first = false;
                     } else {
+                        // The compliance tests actually require ',' rather than ", " :P
                         arrayStringBuilder.append(',');
                     }
                     arrayStringBuilder.append(toString(element));
@@ -158,6 +159,9 @@ default String toString(T value) {
     // BOOLEANs
     ///////////////////////////////
 
+    /**
+     * Creates a BOOLEAN value.
+     */
     T createBoolean(boolean b);
 
     /**
@@ -170,6 +174,9 @@ default String toString(T value) {
     // STRINGs
     ///////////////////////////////
 
+    /**
+     * Creates a STRING value.
+     */
     T createString(String string);
 
     /**
@@ -185,6 +192,9 @@ default String toString(T value) {
     // NUMBERs
     ///////////////////////////////
 
+    /**
+     * Creates a NUMBER value.
+     */
     T createNumber(Number value);
 
     /**
@@ -203,8 +213,14 @@ default String toString(T value) {
     // ARRAYs
     ///////////////////////////////
 
+    /**
+     * Creates a new ArrayBuilder.
+     */
     ArrayBuilder<T> arrayBuilder();
 
+    /**
+     * A builder interface for new ARRAY values.
+     */
     interface ArrayBuilder<T> {
 
         /**
@@ -219,6 +235,9 @@ interface ArrayBuilder<T> {
          */
         void addAll(T collection);
 
+        /**
+         * Builds the new ARRAY value being built.
+         */
         T build();
     }
 
@@ -264,8 +283,14 @@ default T slice(T array, int start, int stop, int step) {
     // OBJECTs
     ///////////////////////////////
 
+    /**
+     * Creates a new ObjectBuilder.
+     */
     ObjectBuilder<T> objectBuilder();
 
+    /**
+     * A builder interface for new OBJECT values.
+     */
     interface ObjectBuilder<T> {
 
         /**
@@ -279,6 +304,9 @@ interface ObjectBuilder<T> {
          */
         void putAll(T object);
 
+        /**
+         * Builds the new OBJECT value being built.
+         */
         T build();
     }