Adding more java docs to the node

[dkrasnoff]

Is your feature request related to a problem? Please describe.
For me, as a developer, it would be the most convenient way to have a Java doc for all Node implementations with markdown examples. It would decrease switching my context from the code base to external sources.

Describe the solution you'd like
I'd like to see the Java doc for all the Node implementations with the markdown examples of elements for which these nodes are related.

[nealhippo]

Hi Dmitrii Krasnov

I had a similar problem trying to understand what nodes where used (especially with extensions).

Wrote a dump class that takes a node and outputs the, class name, attributes of the node (the attributes can be hit and miss depending on how the node implements toStringAttributes) and children, similar to unix tree command.

Not documentation but may help understand what node maps to what markdown.

String markdown = """
        # Heading

        Show text

        - Item 1
          1. Another
        - Item 2
        """;
Node node = parse(markdown);
MarkdownDebug.debug(node);

Outputs:

+--- Document{}
|   +--- Heading{}
|   |   --- Text{literal=Heading}
|   +--- Paragraph{}
|   |   --- Text{literal=Show text}
|   +--- BulletList{}
|   |   +--- ListItem{}
|   |   |   +--- Paragraph{}
|   |   |   |   --- Text{literal=Item 1}
|   |   |   +--- OrderedList{}
|   |   |   |   +--- ListItem{}
|   |   |   |   |   +--- Paragraph{}
|   |   |   |   |   |   --- Text{literal=Another}
|   |   +--- ListItem{}
|   |   |   +--- Paragraph{}
|   |   |   |   --- Text{literal=Item 2}

Class for dumbing a Node it does not need to be the document node is can be
any node.

/**
 * Output the node as a tree similar to Unix tree command.
 * <ul>
 * <li>{@code BlockNode} instances are prefixed by PLUS SIGN U+002B "+".</li>
 * <li>{@code Node} instances are preceded by HYPHEN-MINUS U+002D "-".</li>
 * <li>VERTICAL LINE U+007C "|" show the hierarchy and connections between
 * nodes.</li>
 * </ul>
 */
public class MarkdownDebug {

    /**
     * @param node the node to debug; null output "null"
     */
    public static void debug(@Nullable Node node) {
        if (node == null) {
            System.out.println("null");
        }
        PrintWriter writer = new PrintWriter(System.err, true);
        debug(node, writer);
    }

    /**
     * @param node   the node to debug; null output "null"
     * @param writer the writer to output too
     * @throws NullPointerException if writer is null
     */
    public static void debug(@Nullable Node node, PrintWriter writer) {
        if (writer == null) {
            throw new NullPointerException("'writer' must not be null");
        }
        if (node == null) {
            writer.println("null");
        } else {
            MarkdownDebug debug = new MarkdownDebug(writer);
            debug.visit(node);
        }
    }

    /**
     * @param node the node to debug; null output "null"
     * @return a string representing a tree of nodes
     */
    public static String toString(@Nullable Node node) {
        if (node == null) {
            return "null";
        }
        StringWriter sw = new StringWriter();
        PrintWriter writer = new PrintWriter(sw, true);
        debug(node, writer);
        return sw.toString();
    }

    private final PrintWriter writer;
    private final StringBuilder buffer;

    private MarkdownDebug(PrintWriter writer) {
        this.writer = writer;
        this.buffer = new StringBuilder();
    }

    void visit(Node parent) {
        String d = indent(parent);
        writer.println(d);
        Node node = parent.getFirstChild();
        while (node != null) {
            Node next = node.getNext();
            visit(node);
            node = next;
        }
    }

    // FIXME There is a bug in here that does not stop at the 'node' argument
    // and always iterates to the root node. Although a bug it has not been
    // fixed as this is also quite useful in understanding where the node is
    // relation to the root node. To fix an option should be added that makes
    // the "stops on 'node' argument" optional and the default behaviour as is.
    private String indent(Node node) {
        buffer.setLength(0);
        String last = (node instanceof Block) ? "+--- " : "--- ";
        Node n = node.getParent();
        while (n != null) {
            buffer.append("|   ");
            n = n.getParent();
        }
        buffer.append(last).append(node);
        return buffer.toString();
    }
}

[robinst]

@nealhippo Nice.

@dkrasnoff Yeah agreed the docs there are pretty sparse. Addressing in #370, feel free to comment there.