Added many Javadoc comments. Lightly refactored some code to improve …

…readability and reduce complexity.

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/markup/IMarkupString.java

@@ -49,12 +49,27 @@
 
 public interface IMarkupString<TYPE extends IMarkupString<TYPE>>
     extends ICustomJavaDataType<TYPE> {
+  /**
+   * Get the underlying Flexmark factory supporting markup serialization.
+   *
+   * @return the factory
+   */
   @NonNull
   FlexmarkFactory getFlexmarkFactory();
 
+  /**
+   * Get the top-level Flexmark document node for the markup.
+   *
+   * @return the node
+   */
   @NonNull
   Document getDocument();
 
+  /**
+   * Determine if the markup has no contents.
+   *
+   * @return {@code true} if the markup has no contents or {@code false} otherwise
+   */
   boolean isEmpty();
 
   // /**
@@ -73,15 +88,49 @@ public interface IMarkupString<TYPE extends IMarkupString<TYPE>>
   // throws
   // XMLStreamException;
 
+  /**
+   * Get the HyperText Markup Language (HTML) representation of this markup
+   * string.
+   *
+   * @return the HTML
+   */
   @NonNull
   String toHtml();
 
+  /**
+   * Get the Extensible HyperText Markup Language (XHTML) representation of this
+   * markup string.
+   *
+   * @param namespace
+   *          the XML namespace to use for XHTML elements
+   *
+   * @return the XHTML
+   * @throws XMLStreamException
+   *           if an error occurred while establishing or writing to the
+   *           underlying XML stream
+   * @throws IOException
+   *           if an error occurred while generating the XHTML data
+   */
   @NonNull
   String toXHtml(@NonNull String namespace) throws XMLStreamException, IOException;
 
+  /**
+   * Get the Commonmark Markdown representation of this markup string.
+   *
+   * @return the Markdown
+   */
   @NonNull
   String toMarkdown();
 
+  /**
+   * Get a Markdown representation of this markup string, which will be created by
+   * the provided formatter.
+   *
+   * @param formatter
+   *          the specific Markdown formatter to use in producing the Markdown
+   *
+   * @return the Markdown
+   */
   @NonNull
   String toMarkdown(@NonNull Formatter formatter);
 
@@ -93,6 +142,11 @@ public interface IMarkupString<TYPE extends IMarkupString<TYPE>>
   @NonNull
   Stream<Node> getNodesAsStream();
 
+  /**
+   * Get markup inserts used as place holders within the string.
+   *
+   * @return a list of insets or an empty list if no inserts are present
+   */
   @NonNull
   default List<InsertAnchorNode> getInserts() {
     return getInserts(insert -> true);
@@ -118,10 +172,37 @@ List<InsertAnchorNode> getInserts(
    */
   boolean isBlock();
 
+  /**
+   * Write the Extensible HyperText Markup Language (XHTML) representation of this
+   * markup string to the provided stream writer.
+   *
+   * @param namespace
+   *          the XML namespace to use for XHTML elements
+   * @param streamWriter
+   *          the XML stream to write to
+   * @throws XMLStreamException
+   *           if an error occurred while establishing or writing to the XML
+   *           stream
+   */
   void writeXHtml(
       @NonNull String namespace,
       @NonNull XMLStreamWriter2 streamWriter) throws XMLStreamException;
 
+  /**
+   * Write the Extensible HyperText Markup Language (XHTML) representation of this
+   * markup string to the provided stream writer using the provided XML event
+   * factory.
+   *
+   * @param namespace
+   *          the XML namespace to use for XHTML elements
+   * @param eventFactory
+   *          the XML event factory used to generate XML events to write
+   * @param eventWriter
+   *          the XML event stream to write to
+   * @throws XMLStreamException
+   *           if an error occurred while establishing or writing to the XML
+   *           stream
+   */
   void writeXHtml(
       @NonNull String namespace,
       @NonNull XMLEventFactory2 eventFactory,

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/markup/MarkupLine.java

@@ -56,7 +56,7 @@ public final class MarkupLine
 
   @SuppressWarnings("null")
   @NonNull
-  protected static DataSet newParserOptions() {
+  private static DataSet newParserOptions() {
     MutableDataSet options = new MutableDataSet();
     // disable inline HTML
     options.set(Parser.HTML_BLOCK_PARSER, false);
@@ -72,12 +72,26 @@ protected static DataSet newParserOptions() {
     return FlexmarkConfiguration.newFlexmarkConfig(options);
   }
 
+  /**
+   * Convert the provided HTML string into markup.
+   *
+   * @param html
+   *          the HTML
+   * @return the markup instance
+   */
   @NonNull
   public static MarkupLine fromHtml(@NonNull String html) {
     return new MarkupLine(
         parseHtml(html, FLEXMARK_FACTORY.getFlexmarkHtmlConverter(), FLEXMARK_FACTORY.getMarkdownParser()));
   }
 
+  /**
+   * Convert the provided markdown string into markup.
+   *
+   * @param markdown
+   *          the markup
+   * @return the markup instance
+   */
   @NonNull
   public static MarkupLine fromMarkdown(@NonNull String markdown) {
     return new MarkupLine(parseMarkdown(markdown, FLEXMARK_FACTORY.getMarkdownParser()));
@@ -88,6 +102,12 @@ public FlexmarkFactory getFlexmarkFactory() {
     return FLEXMARK_FACTORY;
   }
 
+  /**
+   * Construct a new single line markup instance.
+   *
+   * @param astNode
+   *          the parsed markup AST
+   */
   protected MarkupLine(@NonNull Document astNode) {
     super(astNode);
     Node child = astNode.getFirstChild();

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/markup/MarkupMultiline.java

@@ -43,7 +43,7 @@ public class MarkupMultiline
    *
    * @param html
    *          the HTML
-   * @return the multiline markup instance
+   * @return the markup instance
    */
   @NonNull
   public static MarkupMultiline fromHtml(@NonNull String html) {
@@ -59,7 +59,7 @@ public static MarkupMultiline fromHtml(@NonNull String html) {
    *
    * @param markdown
    *          the markup
-   * @return the multiline markup instance
+   * @return the markup instance
    */
   @NonNull
   public static MarkupMultiline fromMarkdown(@NonNull String markdown) {

core/src/main/java/gov/nist/secauto/metaschema/core/datatype/markup/flexmark/XmlMarkupParser.java

@@ -74,6 +74,11 @@ public final class XmlMarkupParser {
   @NonNull
   private static final XmlMarkupParser SINGLETON = new XmlMarkupParser();
 
+  /**
+   * Get the singleton markup parser instance.
+   *
+   * @return the instance
+   */
   @SuppressWarnings("PMD.AvoidSynchronizedAtMethodLevel")
   @NonNull
   public static synchronized XmlMarkupParser instance() {
@@ -84,13 +89,31 @@ private XmlMarkupParser() {
     // disable construction
   }
 
+  /**
+   * Parse a single line of markup from XHTML.
+   *
+   * @param reader
+   *          the XML event stream reader
+   * @return the markup string
+   * @throws XMLStreamException
+   *           if an error occurred while parsing
+   */
   public MarkupLine parseMarkupline(XMLEventReader2 reader) throws XMLStreamException { // NOPMD - acceptable
     StringBuilder buffer = new StringBuilder();
     parseContents(reader, null, buffer);
     String html = buffer.toString().trim();
     return html.isEmpty() ? null : MarkupLine.fromHtml(html);
   }
 
+  /**
+   * Parse a markup multiline from XHTML.
+   *
+   * @param reader
+   *          the XML event stream reader
+   * @return the markup string
+   * @throws XMLStreamException
+   *           if an error occurred while parsing
+   */
   public MarkupMultiline parseMarkupMultiline(XMLEventReader2 reader) throws XMLStreamException {
     StringBuilder buffer = new StringBuilder();
     parseToString(reader, buffer);
@@ -102,6 +125,16 @@ public MarkupMultiline parseMarkupMultiline(XMLEventReader2 reader) throws XMLSt
     return html.isEmpty() ? null : MarkupMultiline.fromHtml(html);
   }
 
+  /**
+   * Parse a markup multiline from XHTML.
+   *
+   * @param reader
+   *          the XML event stream reader
+   * @param buffer
+   *          the markup string buffer
+   * @throws XMLStreamException
+   *           if an error occurred while parsing
+   */
   private void parseToString(XMLEventReader2 reader, StringBuilder buffer) // NOPMD - acceptable
       throws XMLStreamException {
     // if (LOGGER.isDebugEnabled()) {

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/antlr/AbstractAstVisitor.java

@@ -531,6 +531,7 @@ public R visitEqname(EqnameContext ctx) {
    *          the provided expression context
    * @return the result
    */
+  @NonNull
   protected abstract R handleWildcard(@NonNull WildcardContext ctx);
 
   @Override

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractCSTVisitorBase.java

@@ -49,6 +49,9 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
+@SuppressWarnings({
+    "PMD.CouplingBetweenObjects"
+})
 public abstract class AbstractCSTVisitorBase
     extends AbstractAstVisitor<IExpression> {
 
@@ -131,6 +134,27 @@ public IExpression visit(ParseTree tree) {
     return super.visit(tree);
   }
 
+  /**
+   * Parse the provided context as an n-ary phrase.
+   *
+   * @param <CONTEXT>
+   *          the Java type of the antlr context to parse
+   * @param <T>
+   *          the Java type of the child expressions produced by this parser
+   * @param <R>
+   *          the Java type of the outer expression produced by the parser
+   * @param context
+   *          the antlr context to parse
+   * @param startIndex
+   *          the child index to start parsing on
+   * @param step
+   *          the increment to advance while parsing child expressions
+   * @param parser
+   *          a binary function used to produce child expressions
+   * @param supplier
+   *          a function used to produce the other expression
+   * @return the outer expression or {@code null} if no children exist to parse
+   */
   @Nullable
   protected <CONTEXT extends ParserRuleContext, T extends IExpression, R extends IExpression>
       R nairyToCollection(