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/AbstractMarkupString.java

@@ -38,8 +38,8 @@
 import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.FlexmarkFactory;
 import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.IMarkupVisitor;
 import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.IMarkupWriter;
+import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.InsertAnchorExtension;
 import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.InsertAnchorExtension.InsertAnchorNode;
-import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.InsertVisitor;
 import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.MarkupVisitor;
 import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.MarkupXmlEventWriter;
 import gov.nist.secauto.metaschema.core.datatype.markup.flexmark.MarkupXmlStreamWriter;
@@ -288,7 +288,7 @@ public List<InsertAnchorNode> getInserts() {
   @Override
   @NonNull
   public List<InsertAnchorNode> getInserts(@NonNull Predicate<InsertAnchorNode> filter) {
-    InsertVisitor visitor = new InsertVisitor(filter);
+    InsertAnchorExtension.InsertVisitor visitor = new InsertAnchorExtension.InsertVisitor(filter);
     visitor.visitChildren(getDocument());
     return visitor.getInserts();
   }

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);
@@ -66,18 +66,32 @@ protected static DataSet newParserOptions() {
 
     Collection<Extension> currentExtensions = Parser.EXTENSIONS.get(FlexmarkConfiguration.FLEXMARK_CONFIG);
     List<Extension> extensions = new LinkedList<>(currentExtensions);
-    extensions.add(SuppressPTagExtension.create());
+    extensions.add(SuppressPTagExtension.newInstance());
     Parser.EXTENSIONS.set(options, extensions);
 
     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/FlexmarkConfiguration.java

@@ -65,13 +65,13 @@ private static DataSet initFlexmarkConfig() {
 
     List<Extension> extensions = List.of(
         // Metaschema insert
-        InsertAnchorExtension.create(),
+        InsertAnchorExtension.newInstance(),
         // q tag handling
-        HtmlQuoteTagExtension.create(),
+        HtmlQuoteTagExtension.newInstance(),
         TypographicExtension.create(),
         TablesExtension.create(),
         // fix for code handling
-        HtmlCodeRenderExtension.create(),
+        HtmlCodeRenderExtension.newInstance(),
         // to ensure that escaped characters are not lost
         EscapedCharacterExtension.create(),
         SuperscriptExtension.create(),

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

@@ -35,6 +35,10 @@
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
+/**
+ * Provides factory methods for Flexmark processing to support HTML-to-markdown
+ * and markdown-to-HTML conversion.
+ */
 @SuppressWarnings("PMD.DataClass")
 public final class FlexmarkFactory {
   @NonNull
@@ -50,12 +54,25 @@ public final class FlexmarkFactory {
   @NonNull
   final ListOptions listOptions;
 
+  /**
+   * Get the static Flexmark factory instance.
+   *
+   * @return the instance
+   */
   @SuppressWarnings("PMD.AvoidSynchronizedAtMethodLevel")
   @NonNull
   public static synchronized FlexmarkFactory instance() {
     return SINGLETON;
   }
 
+  /**
+   * Get a Flexmark factory instance that uses the provided Flexmark
+   * configuration.
+   *
+   * @param config
+   *          the Flexmark configuration
+   * @return the instance
+   */
   @NonNull
   public static FlexmarkFactory newInstance(@NonNull DataHolder config) {
     return new FlexmarkFactory(config);
@@ -76,26 +93,54 @@ private FlexmarkFactory(@NonNull DataHolder config) {
     this.listOptions = ListOptions.get(config);
   }
 
+  /**
+   * Get configured options for processing HTML and markdown lists.
+   *
+   * @return the options
+   */
   @NonNull
   public ListOptions getListOptions() {
     return listOptions;
   }
 
+  /**
+   * Get the Flexmark markdown parser, which can produce a markdown syntax tree.
+   *
+   * @return the parser
+   */
   @NonNull
   public Parser getMarkdownParser() {
     return markdownParser;
   }
 
+  /**
+   * Get the Flexmark HTML renderer, which can produce HTML from a markdown syntax
+   * tree.
+   *
+   * @return the parser
+   */
   @NonNull
   public HtmlRenderer getHtmlRenderer() {
     return htmlRenderer;
   }
 
+  /**
+   * Get the Flexmark formatter, which can produce markdown from a markdown syntax
+   * tree.
+   *
+   * @return the parser
+   */
   @NonNull
   public Formatter getFormatter() {
     return formatter;
   }
 
+  /**
+   * Get the Flexmark HTML converter, which can produce markdown from HTML
+   * content.
+   *
+   * @return the parser
+   */
   @NonNull
   public FlexmarkHtmlConverter getFlexmarkHtmlConverter() {
     return htmlConverter;

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

@@ -57,7 +57,12 @@ public class HtmlCodeRenderExtension
     implements HtmlRenderer.HtmlRendererExtension {
   private static final Pattern EOL_PATTERN = Pattern.compile("\r\n|\r|\n");
 
-  public static HtmlCodeRenderExtension create() {
+  /**
+   * Construct a new extension instance.
+   *
+   * @return the instance
+   */
+  public static HtmlCodeRenderExtension newInstance() {
     return new HtmlCodeRenderExtension();
   }
 

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

@@ -61,7 +61,12 @@ public class HtmlQuoteTagExtension
     implements Parser.ParserExtension, HtmlRenderer.HtmlRendererExtension,
     FlexmarkHtmlConverter.HtmlConverterExtension {
 
-  public static HtmlQuoteTagExtension create() {
+  /**
+   * Construct a new extension instance.
+   *
+   * @return the instance
+   */
+  public static HtmlQuoteTagExtension newInstance() {
     return new HtmlQuoteTagExtension();
   }
 
@@ -172,6 +177,12 @@ public HtmlNodeRenderer apply(DataHolder options) {
   public static class DoubleQuoteNode
       extends TypographicQuotes {
 
+    /**
+     * Construct a new double quote node.
+     *
+     * @param node
+     *          the typographic information pertaining to a double quote
+     */
     @SuppressWarnings("PMD.ConstructorCallsOverridableMethod")
     public DoubleQuoteNode(TypographicQuotes node) {
       super(node.getOpeningMarker(), node.getText(), node.getClosingMarker());

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

@@ -33,5 +33,15 @@
 
 @SuppressFBWarnings("THROWS_METHOD_THROWS_CLAUSE_THROWABLE")
 public interface IMarkupVisitor<T, E extends Throwable> {
+  /**
+   * A visitor callback used to visit a markdown syntax tree.
+   *
+   * @param document
+   *          the markdown syntax tree
+   * @param writer
+   *          a markup writer used to generate markup output
+   * @throws E
+   *           the visitor exception Java type
+   */
   void visitDocument(@NonNull Document document, @NonNull IMarkupWriter<T, E> writer) throws E;
 }