Address code review feedback

- Fix IFunctionResolver Javadoc to remove incorrect null return mention
  (method is @nonnull and throws exception on no match)

- Fix InvalidTreatTypeDynamicMetapathException to register the evaluationStack
  parameter by calling registerEvaluationContext()

- Add registerEvaluationContext(Deque) method to MetapathException for
  registering evaluation stack directly

- Fix IContainerModelGrouped Javadoc to correctly describe Collection return
  types instead of "ordered mapping"

- Fix validation/package-info.java to link to IConstraint type instead of
  package (avoids doclint warnings)

- Add Objects.requireNonNull in ExceptionUtils.wrap() and have wrapAndThrow()
  delegate to wrap() to avoid duplication

- Fix flexmark/impl/package-info.java Javadoc formatting for SuppressPTagExtension

Author: david-waltermire

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/markup/flexmark/impl/package-info.java

@@ -41,10 +41,7 @@
  * <ul>
  * <li>{@link HtmlCodeRenderExtension} - Custom rendering for inline
  * {@code <code>} elements to properly handle special characters</li>
- * <li>{@link SuppressPTagExtension} - Suppresses {@code
- *
-<p>
- * } paragraph tags in single-line markup content</li>
+ * <li>{@link SuppressPTagExtension} - Suppresses paragraph tags in single-line markup content</li>
  * <li>{@link FixedEmphasisDelimiterProcessor} - Fixed implementation of
  * emphasis delimiter processing to handle edge cases in Markdown emphasis
  * parsing</li>

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/InvalidTreatTypeDynamicMetapathException.java

@@ -34,6 +34,7 @@ public InvalidTreatTypeDynamicMetapathException(
       @NonNull Deque<IExpression> evaluationStack,
       @Nullable String message) {
     super(TREAT_DOES_NOT_MATCH_TYPE, message);
+    registerEvaluationContext(evaluationStack);
   }
 
   /**

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/MetapathException.java

@@ -102,6 +102,22 @@ public MetapathException registerEvaluationContext(@NonNull DynamicContext dynam
     return this;
   }
 
+  /**
+   * Registers the evaluation context from the provided evaluation stack.
+   * <p>
+   * A snapshot of the stack is captured if not already set.
+   *
+   * @param stack
+   *          the evaluation stack recording the expressions being evaluated
+   * @return this exception instance for chaining
+   */
+  public MetapathException registerEvaluationContext(@NonNull Deque<? extends IExpression> stack) {
+    if (evaluationStack == null) {
+      evaluationStack = new ArrayDeque<>(stack);
+    }
+    return this;
+  }
+
   /**
    * Registers the evaluation context from the provided metapath expression.
    * <p>

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/function/IFunctionResolver.java

@@ -17,14 +17,14 @@
 public interface IFunctionResolver {
   /**
    * Retrieve the function with the provided name that supports the signature of
-   * the provided methods, if such a function exists.
+   * the provided methods.
    *
    * @param name
    *          the name of a group of functions
    * @param arity
    *          the count of arguments for use in determining an argument signature
    *          match
-   * @return the matching function or {@code null} if no match exists
+   * @return the matching function
    * @throws StaticMetapathException
    *           with the code {@link StaticMetapathException#NO_FUNCTION_MATCH} if
    *           a matching function was not found

core/src/main/java/gov/nist/secauto/metaschema/core/model/IContainerModelGrouped.java

@@ -31,7 +31,7 @@ default Collection<? extends INamedModelInstanceGrouped> getModelInstances() {
   /**
    * Get all named model instances within the container.
    *
-   * @return an ordered mapping of use name to model instance
+   * @return the named model instances in this container
    */
   @Override
   @NonNull
@@ -53,7 +53,7 @@ default Collection<? extends INamedModelInstanceGrouped> getModelInstances() {
   /**
    * Get all field instances within the container.
    *
-   * @return a mapping of use name to field instance
+   * @return the field instances in this container
    */
   @Override
   @NonNull
@@ -75,7 +75,7 @@ default Collection<? extends INamedModelInstanceGrouped> getModelInstances() {
   /**
    * Get all assembly instances within the container.
    *
-   * @return a mapping of use name to assembly instance
+   * @return the assembly instances in this container
    */
   @Override
   @NonNull

core/src/main/java/gov/nist/secauto/metaschema/core/model/validation/package-info.java

@@ -26,7 +26,8 @@
  * <h2>Usage Context</h2>
  * <p>
  * This validation framework differs from constraint validation
- * ({@link gov.nist.secauto.metaschema.core.model.constraint}) in that it:
+ * ({@link gov.nist.secauto.metaschema.core.model.constraint.IConstraint}) in
+ * that it:
  * <ul>
  * <li>Validates against schema documents (XSD/JSON Schema) rather than
  * constraint rules</li>
@@ -39,9 +40,10 @@
  * <p>
  * For constraint-based validation (e.g., allowed values, uniqueness,
  * cardinality), use the
- * {@link gov.nist.secauto.metaschema.core.model.constraint} package instead.
+ * {@link gov.nist.secauto.metaschema.core.model.constraint.IConstraint}
+ * instead.
  *
- * @see gov.nist.secauto.metaschema.core.model.constraint
+ * @see gov.nist.secauto.metaschema.core.model.constraint.IConstraint
  */
 
 package gov.nist.secauto.metaschema.core.model.validation;

core/src/main/java/gov/nist/secauto/metaschema/core/util/ExceptionUtils.java

@@ -5,6 +5,8 @@
 
 package gov.nist.secauto.metaschema.core.util;
 
+import java.util.Objects;
+
 import edu.umd.cs.findbugs.annotations.NonNull;
 
 /**
@@ -24,7 +26,7 @@ public final class ExceptionUtils {
    */
   @NonNull
   public static WrappedException wrap(@NonNull Throwable ex) {
-    return new WrappedException(ex);
+    return new WrappedException(Objects.requireNonNull(ex, "ex"));
   }
 
   /**
@@ -39,7 +41,7 @@ public static WrappedException wrap(@NonNull Throwable ex) {
    */
   @NonNull
   public static WrappedException wrapAndThrow(@NonNull Throwable ex) {
-    return new WrappedException(ex);
+    return wrap(ex);
   }
 
   /**