Add docs with examples to Node classes

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

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

@@ -1,5 +1,17 @@
 package org.commonmark.node;
 
+/**
+ * A heading, e.g.:
+ * <pre>
+ * First heading
+ * =============
+ *
+ * ## Another heading
+ * </pre>
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#atx-headings">CommonMark Spec: ATX headings</a>
+ * @see <a href="https://spec.commonmark.org/0.31.2/#setext-headings">CommonMark Spec: Setext headings</a>
+ */
 public class Heading extends Block {
 
     private int level;

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

@@ -1,5 +1,13 @@
 package org.commonmark.node;
 
+/**
+ * An image, e.g.:
+ * <pre>
+ * ![foo](/url "title")
+ * </pre>
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#images">CommonMark Spec</a>
+ */
 public class Image extends Node {
 
     private String destination;

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

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

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

@@ -18,7 +18,7 @@
  * Note that the text in the link can contain inline formatting, so it could also contain an {@link Image} or
  * {@link Emphasis}, etc.
  *
- * @see <a href="http://spec.commonmark.org/0.31.2/#links">CommonMark Spec for links</a>
+ * @see <a href="http://spec.commonmark.org/0.31.2/#links">CommonMark Spec</a>
  */
 public class Link extends Node {
 

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

@@ -9,7 +9,7 @@
  * They can be referenced anywhere else in the document to produce a link using <code>[foo]</code>. The definitions
  * themselves are usually not rendered in the final output.
  *
- * @see <a href="https://spec.commonmark.org/0.31.2/#link-reference-definition">Link reference definitions</a>
+ * @see <a href="https://spec.commonmark.org/0.31.2/#link-reference-definition">CommonMark Spec</a>
  */
 public class LinkReferenceDefinition extends Block {
 

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

@@ -1,5 +1,8 @@
 package org.commonmark.node;
 
+/**
+ * A list block like {@link BulletList} or {@link OrderedList}.
+ */
 public abstract class ListBlock extends Block {
 
     private boolean tight;

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

@@ -1,5 +1,10 @@
 package org.commonmark.node;
 
+/**
+ * A child of a {@link ListBlock}, containing other blocks (e.g. {@link Paragraph}, other lists, etc).
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#list-items">CommonMark Spec: List items</a>
+ */
 public class ListItem extends Block {
 
     private Integer markerIndent;

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

@@ -1,5 +1,17 @@
 package org.commonmark.node;
 
+/**
+ * An ordered list, e.g.:
+ * <pre><code>
+ * 1. One
+ * 2. Two
+ * 3. Three
+ * </code></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 OrderedList extends ListBlock {
 
     private String markerDelimiter;

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

@@ -2,6 +2,8 @@
 
 /**
  * A paragraph block, contains inline nodes such as {@link Text}
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#paragraphs">CommonMark Spec</a>
  */
 public class Paragraph extends Block {
 

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

@@ -1,5 +1,14 @@
 package org.commonmark.node;
 
+/**
+ * A soft line break (as opposed to a {@link HardLineBreak}), e.g. between:
+ * <pre>
+ * foo
+ * bar
+ * </pre>
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#soft-line-breaks">CommonMark Spec</a>
+ */
 public class SoftLineBreak extends Node {
 
     @Override

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

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

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

@@ -1,5 +1,15 @@
 package org.commonmark.node;
 
+/**
+ * A text node, e.g. in:
+ * <pre>
+ * foo *bar*
+ * </pre>
+ * <p>
+ * The <code>foo </code> is a text node, and the <code>bar</code> inside the emphasis is also a text node.
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#textual-content">CommonMark Spec</a>
+ */
 public class Text extends Node {
 
     private String literal;

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

@@ -1,5 +1,17 @@
 package org.commonmark.node;
 
+/**
+ * A thematic break, e.g. between text:
+ * <pre>
+ * Some text
+ *
+ * ___
+ *
+ * Some other text.
+ * </pre>
+ *
+ * @see <a href="https://spec.commonmark.org/0.31.2/#thematic-breaks">CommonMark Spec</a>
+ */
 public class ThematicBreak extends Block {
 
     private String literal;