Merge pull request #403 from commonmark/list-item-docs

Add docs to ListItem and its appendChild about tight lists

Author: robinst

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

@@ -2,6 +2,10 @@
 
 /**
  * A child of a {@link ListBlock}, containing other blocks (e.g. {@link Paragraph}, other lists, etc).
+ * <p>
+ * Note that a list item can't directly contain {@link Text}, it needs to be:
+ * {@link ListItem} : {@link Paragraph} : {@link Text}.
+ * If you want a list that is rendered tightly, create a list with {@link ListBlock#setTight(boolean)}.
  *
  * @see <a href="https://spec.commonmark.org/0.31.2/#list-items">CommonMark Spec: List items</a>
  */
@@ -57,4 +61,18 @@ public Integer getContentIndent() {
     public void setContentIndent(Integer contentIndent) {
         this.contentIndent = contentIndent;
     }
+
+    /**
+     * @deprecated list items should only contain block nodes; if you're trying to create a list that is rendered
+     * without paragraphs, use {@link ListBlock#setTight(boolean)} instead.
+     */
+    @Override
+    @Deprecated
+    public void appendChild(Node child) {
+        super.appendChild(child);
+    }
+
+    public void appendChild(Block child) {
+        super.appendChild(child);
+    }
 }