Add docs with examples to Node classes

Author: robinst

CHANGELOG.md

@@ -8,6 +8,7 @@ with the exception that 0.x versions can break between minor versions.
 
 ## [Unreleased]
 ### Added
+- More documentation with examples for `Node` classes
 ### Changed
 ### Fixed
 - `MarkdownRenderer`: Fix precedence for `nodeRendererFactory`: Factories passed

commonmark/src/main/java/org/commonmark/node/BlockQuote.java

@@ -1,5 +1,15 @@
 package org.commonmark.node;
 
+/**
+ * A block quote, e.g.:
+ * <pre>
+ * &gt; Some quoted text
+ * </pre>
+ * <p>
+ * Note that child nodes are themselves blocks, e.g. {@link Paragraph}, {@link ListBlock} etc.
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#block-quotes">CommonMark Spec</a>
+ */
 public class BlockQuote extends Block {
 
     @Override

commonmark/src/main/java/org/commonmark/node/BulletList.java

@@ -1,5 +1,17 @@
 package org.commonmark.node;
 
+/**
+ * A bullet list, e.g.:
+ * <pre>
+ * - One
+ * - Two
+ * - Three
+ * </pre>
+ * <p>
+ * The children are {@link ListItem} blocks, which contain other blocks (or nested lists).
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#list-items">CommonMark Spec: List items</a>
+ */
 public class BulletList extends ListBlock {
 
     private String marker;

commonmark/src/main/java/org/commonmark/node/Code.java

@@ -1,5 +1,13 @@
 package org.commonmark.node;
 
+/**
+ * Inline code span, e.g.:
+ * <pre>
+ * Some `inline code`
+ * </pre>
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#code-spans">CommonMark Spec</a>
+ */
 public class Code extends Node {
 
     private String literal;
@@ -16,6 +24,10 @@ public void accept(Visitor visitor) {
         visitor.visit(this);
     }
 
+    /**
+     * @return the literal text in the code span (note that it's not necessarily the raw text between tildes,
+     * e.g. when spaces are stripped)
+     */
     public String getLiteral() {
         return literal;
     }

commonmark/src/main/java/org/commonmark/node/CustomBlock.java

@@ -1,5 +1,8 @@
 package org.commonmark.node;
 
+/**
+ * A block that extensions can subclass to define custom blocks (not part of the core specification).
+ */
 public abstract class CustomBlock extends Block {
 
     @Override

commonmark/src/main/java/org/commonmark/node/CustomNode.java

@@ -1,5 +1,8 @@
 package org.commonmark.node;
 
+/**
+ * A node that extensions can subclass to define custom nodes (not part of the core specification).
+ */
 public abstract class CustomNode extends Node {
     @Override
     public void accept(Visitor visitor) {

commonmark/src/main/java/org/commonmark/node/Document.java

@@ -1,5 +1,8 @@
 package org.commonmark.node;
 
+/**
+ * The root block of a document, containing the top-level blocks.
+ */
 public class Document extends Block {
 
     @Override

commonmark/src/main/java/org/commonmark/node/Emphasis.java

@@ -1,5 +1,13 @@
 package org.commonmark.node;
 
+/**
+ * Emphasis, e.g.:
+ * <pre>
+ * Some *emphasis* or _emphasis_
+ * </pre>
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#emphasis-and-strong-emphasis">CommonMark Spec: Emphasis and strong emphasis</a>
+ */
 public class Emphasis extends Node implements Delimited {
 
     private String delimiter;

commonmark/src/main/java/org/commonmark/node/FencedCodeBlock.java

@@ -1,5 +1,17 @@
 package org.commonmark.node;
 
+/**
+ * A fenced code block, e.g.:
+ * <pre>
+ * ```
+ * foo
+ * bar
+ * ```
+ * </pre>
+ * <p>
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#fenced-code-blocks">CommonMark Spec</a>
+ */
 public class FencedCodeBlock extends Block {
 
     private String fenceCharacter;

commonmark/src/main/java/org/commonmark/node/HardLineBreak.java

@@ -1,5 +1,15 @@
 package org.commonmark.node;
 
+/**
+ * A hard line break, e.g.:
+ * <pre>
+ * line\
+ * break
+ * </pre>
+ * <p>
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#hard-line-breaks">CommonMark Spec</a>
+ */
 public class HardLineBreak extends Node {
 
     @Override