Added API documentation to src/cmark.h. Closes #224.

3 files changed, 332 insertions, 165 deletions

diff --git a/man/make_man_page.py b/man/make_man_page.py
index dd226e6..2a7f9ab 100644
--- a/man/make_man_page.py
+++ b/man/make_man_page.py
@@ -47,7 +47,7 @@ single_quote_re = re.compile("(?<!\w)'([^']+)'(?!\w)")
 double_quote_re = re.compile("(?<!\w)''([^']+)''(?!\w)")
 
 def handle_quotes(s):
-    return re.sub(double_quote_re, '\\\\fB\g<1>\\\\f[]', re.sub(single_quote_re, '\\\\fI\g<1>\\\\f[]', s))
+    return re.sub(double_quote_re, '**\g<1>**', re.sub(single_quote_re, '*\g<1>*', s))
 
 typedef = False
 mdlines = []
@@ -91,6 +91,7 @@ with open(sourcefile, 'r') as cmarkh:
                 mdlines.append('\n')
             rawsig = ''.join(sig)
             m = function_re.match(rawsig)
+            mdlines.append('.PP\n')
             if m:
                 mdlines.append('\\fI' + m.group('type') + '\\f[]' + ' ')
                 mdlines.append('\\fB' + m.group('name') + '\\f[]' + '(')
@@ -107,7 +108,7 @@ with open(sourcefile, 'r') as cmarkh:
                 mdlines.append('.RE\n\\f[]\n.fi\n')
             if len(mdlines) > 0 and mdlines[-1] != '\n':
                 mdlines.append('\n')
-            mdlines += chunk
+            mdlines += md2man(''.join(chunk))
             mdlines.append('\n')
             chunk = []
             sig = []
diff --git a/man/man3/cmark.3 b/man/man3/cmark.3
index 68ce528..589ffe1 100644
--- a/man/man3/cmark.3
+++ b/man/man3/cmark.3
@@ -9,6 +9,7 @@ DESCRIPTION
 .SS
 Simple Interface
 
+.PP
 .nf
 \fC
 .RS 0n
@@ -17,281 +18,383 @@ Simple Interface
 \f[]
 .fi
 
+.PP
 Current version of library.
 
+.PP
 \fIchar *\f[] \fBcmark_markdown_to_html\f[](\fIconst char *text\f[], \fIint len\f[])
 
-Convert \fItext\f[] (assumed to be a UTF-8 encoded string with length
-\fIlen\f[] from CommonMark Markdown to HTML, returning a null-terminated,
-UTF-8-encoded string.
+.PP
+Convert \f[I]text\f[] (assumed to be a UTF\-8 encoded string with length
+\f[I]len\f[] from CommonMark Markdown to HTML, returning a null\-terminated,
+UTF\-8\-encoded string.
 
 .SS
 Node Structure
 
-.nf
-\fC
-.RS 0n
-typedef enum {
-	/* Error status */
-	CMARK_NODE_NONE,
-
-	/* Block */
-	CMARK_NODE_DOCUMENT,
-	CMARK_NODE_BLOCK_QUOTE,
-	CMARK_NODE_LIST,
-	CMARK_NODE_LIST_ITEM,
-	CMARK_NODE_CODE_BLOCK,
-	CMARK_NODE_HTML,
-	CMARK_NODE_PARAGRAPH,
-	CMARK_NODE_HEADER,
-	CMARK_NODE_HRULE,
-
-	CMARK_NODE_FIRST_BLOCK = CMARK_NODE_DOCUMENT,
-	CMARK_NODE_LAST_BLOCK  = CMARK_NODE_HRULE,
-
-	/* Inline */
-	CMARK_NODE_TEXT,
-	CMARK_NODE_SOFTBREAK,
-	CMARK_NODE_LINEBREAK,
-	CMARK_NODE_INLINE_CODE,
-	CMARK_NODE_INLINE_HTML,
-	CMARK_NODE_EMPH,
-	CMARK_NODE_STRONG,
-	CMARK_NODE_LINK,
-	CMARK_NODE_IMAGE,
-
-	CMARK_NODE_FIRST_INLINE = CMARK_NODE_TEXT,
-	CMARK_NODE_LAST_INLINE  = CMARK_NODE_IMAGE,
-} cmark_node_type;
-.RE
-\f[]
-.fi
-
-
-
-.nf
-\fC
-.RS 0n
-typedef enum {
-	CMARK_NO_LIST,
-	CMARK_BULLET_LIST,
-	CMARK_ORDERED_LIST
-}  cmark_list_type;
-.RE
-\f[]
-.fi
-
-
-
-.nf
-\fC
-.RS 0n
-typedef enum {
-	CMARK_PERIOD_DELIM,
-	CMARK_PAREN_DELIM
-} cmark_delim_type;
-.RE
-\f[]
-.fi
-
-
-
 .SS
 Creating and Destroying Nodes
 
+.PP
 \fIcmark_node*\f[] \fBcmark_node_new\f[](\fIcmark_node_type type\f[])
 
+.PP
+Creates a new node of type \f[I]type\f[]\&.  Note that the node may have
+other required properties, which it is the caller's responsibility
+to assign.
 
-
+.PP
 \fIvoid\f[] \fBcmark_node_free\f[](\fIcmark_node *node\f[])
 
-
+.PP
+Frees the memory allocated for a node.
 
 .SS
 Tree Traversal
 
-\fIcmark_node*\f[] \fBcmark_node_previous\f[](\fIcmark_node *node\f[])
+.PP
+\fIcmark_node*\f[] \fBcmark_node_next\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the next node in the sequence after \f[I]node\f[], or NULL if
+there is none.
 
+.PP
+\fIcmark_node*\f[] \fBcmark_node_previous\f[](\fIcmark_node *node\f[])
 
-\fIcmark_node*\f[] \fBcmark_node_parent\f[](\fIcmark_node *node\f[])
+.PP
+Returns the previous node in the sequence after \f[I]node\f[], or NULL if
+there is none.
 
+.PP
+\fIcmark_node*\f[] \fBcmark_node_parent\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the parent of \f[I]node\f[], or NULL if there is none.
 
+.PP
 \fIcmark_node*\f[] \fBcmark_node_first_child\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the first child of \f[I]node\f[], or NULL if \f[I]node\f[] has no children.
 
-
+.PP
 \fIcmark_node*\f[] \fBcmark_node_last_child\f[](\fIcmark_node *node\f[])
 
-
+.PP
+Returns the last child of \f[I]node\f[], or NULL if \f[I]node\f[] has no children.
 
 .SS
 Iterator
+.PP
+An iterator will walk through a tree of nodes, starting from a root
+node, returning one node at a time, together with information about
+whether the node is being entered or exited.  The iterator will
+first descend to a child node, if there is one.  When there is no
+child, the iterator will go to the next sibling.  When there is no
+next sibling, the iterator will return to the parent (but with
+a \f[I]cmark_event_type\f[] of \f[C]CMARK_EVENT_EXIT\f[]).  The iterator will
+return \f[C]CMARK_EVENT_DONE\f[] when it reaches the root node again.
+One natural application is an HTML renderer, where an \f[C]ENTER\f[] event
+outputs an open tag and an \f[C]EXIT\f[] event outputs a close tag.
+An iterator might also be used to transform an AST in some systematic
+way, for example, turning all level\-3 headers into regular paragraphs.
+.IP
+.nf
+\f[C]
+void
+usage_example(cmark_node *root) {
+    cmark_event_type ev_type;
+    cmark_iter *iter = cmark_iter_new(root);
+
+    while ((ev_type = cmark_iter_next(iter)) != CMARK_EVENT_DONE) {
+        cmark_node *cur = cmark_iter_get_node(iter);
+        // Do something with `cur` and `ev_type`
+    }
+
+    cmark_iter_free(iter);
+}
+\f[]
+.fi
 
+.PP
 \fIcmark_iter*\f[] \fBcmark_iter_new\f[](\fIcmark_node *root\f[])
 
+.PP
+Creates a new iterator starting at \f[I]root\f[]\&.
 
-
+.PP
 \fIvoid\f[] \fBcmark_iter_free\f[](\fIcmark_iter *iter\f[])
 
+.PP
+Frees the memory allocated for an iterator.
 
-
+.PP
 \fIcmark_event_type\f[] \fBcmark_iter_next\f[](\fIcmark_iter *iter\f[])
 
+.PP
+Returns the event type (\f[C]CMARK_EVENT_ENTER\f[], \f[C]CMARK_EVENT_EXIT\f[],
+or \f[C]CMARK_EVENT_DONE\f[]) for the next node.
 
-
+.PP
 \fIcmark_node*\f[] \fBcmark_iter_get_node\f[](\fIcmark_iter *iter\f[])
 
-
+.PP
+Returns the next node in the sequence described above.
 
 .SS
 Accessors
 
+.PP
 \fIcmark_node_type\f[] \fBcmark_node_get_type\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the type of \f[I]node\f[], or \f[C]CMARK_NODE_NONE\f[] on error.
 
-
+.PP
 \fIconst char*\f[] \fBcmark_node_get_string_content\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the string contents of \f[I]node\f[], or NULL if none.
 
-
+.PP
 \fIint\f[] \fBcmark_node_set_string_content\f[](\fIcmark_node *node\f[], \fIconst char *content\f[])
 
+.PP
+Sets the string contents of \f[I]node\f[]\&.  Returns 1 on success,
+0 on failure.
 
-
+.PP
 \fIint\f[] \fBcmark_node_get_header_level\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the header level of \f[I]node\f[], or 0 if \f[I]node\f[] is not a header.
 
-
+.PP
 \fIint\f[] \fBcmark_node_set_header_level\f[](\fIcmark_node *node\f[], \fIint level\f[])
 
+.PP
+Sets the header level of \f[I]node\f[], returning 1 on success and 0 on error.
 
-
+.PP
 \fIcmark_list_type\f[] \fBcmark_node_get_list_type\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the list type of \f[I]node\f[], or \f[C]CMARK_NO_LIST\f[] if \f[I]node\f[]
+is not a list.
 
-
+.PP
 \fIint\f[] \fBcmark_node_set_list_type\f[](\fIcmark_node *node\f[], \fIcmark_list_type type\f[])
 
+.PP
+Sets the list type of \f[I]node\f[], returning 1 on success and 0 on error.
 
-
+.PP
 \fIint\f[] \fBcmark_node_get_list_start\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns starting number of \f[I]node\f[], if it is an ordered list, otherwise 0.
 
-
+.PP
 \fIint\f[] \fBcmark_node_set_list_start\f[](\fIcmark_node *node\f[], \fIint start\f[])
 
+.PP
+Sets starting number of \f[I]node\f[], if it is an ordered list. Returns 1
+on success, 0 on failure.
 
-
+.PP
 \fIint\f[] \fBcmark_node_get_list_tight\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns 1 if \f[I]node\f[] is a tight list, 0 otherwise.
 
-
+.PP
 \fIint\f[] \fBcmark_node_set_list_tight\f[](\fIcmark_node *node\f[], \fIint tight\f[])
 
+.PP
+Sets the "tightness" of a list.  Returns 1 on success, 0 on failure.
 
-
+.PP
 \fIconst char*\f[] \fBcmark_node_get_fence_info\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the info string from a fenced code block, or NULL if none.
 
-
+.PP
 \fIint\f[] \fBcmark_node_set_fence_info\f[](\fIcmark_node *node\f[], \fIconst char *info\f[])
 
+.PP
+Sets the info string in a fenced code block, returning 1 on
+success and 0 on failure.
 
-
+.PP
 \fIconst char*\f[] \fBcmark_node_get_url\f[](\fIcmark_node *node\f[])
 
+.PP
+Gets the URL of a link or image \f[I]node\f[], or NULL if none.
 
-
+.PP
 \fIint\f[] \fBcmark_node_set_url\f[](\fIcmark_node *node\f[], \fIconst char *url\f[])
 
+.PP
+Sets the URL of a link or image \f[I]node\f[]\&. Returns 1 on success,
+0 on failure.
 
-
+.PP
 \fIconst char*\f[] \fBcmark_node_get_title\f[](\fIcmark_node *node\f[])
 
+.PP
+Gets the title of a link or image \f[I]node\f[], or NULL if none.
 
-
+.PP
 \fIint\f[] \fBcmark_node_set_title\f[](\fIcmark_node *node\f[], \fIconst char *title\f[])
 
+.PP
+Sets the title of a link or image \f[I]node\f[]\&. Returns 1 on success,
+0 on failure.
 
-
+.PP
 \fIint\f[] \fBcmark_node_get_start_line\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the line on which \f[I]node\f[] begins.
 
-
+.PP
 \fIint\f[] \fBcmark_node_get_start_column\f[](\fIcmark_node *node\f[])
 
+.PP
+Returns the column at which \f[I]node\f[] begins.
 
-
+.PP
 \fIint\f[] \fBcmark_node_get_end_line\f[](\fIcmark_node *node\f[])
 
-
+.PP
+Returns the line on which \f[I]node\f[] ends.
 
 .SS
 Tree Manipulation
 
+.PP
 \fIvoid\f[] \fBcmark_node_unlink\f[](\fIcmark_node *node\f[])
 
+.PP
+Unlinks a \f[I]node\f[], removing it from the tree, but not freeing its
+memory.  (Use \f[I]cmark_node_free\f[] for that.)
 
-
+.PP
 \fIint\f[] \fBcmark_node_insert_before\f[](\fIcmark_node *node\f[], \fIcmark_node *sibling\f[])
 
+.PP
+Inserts \f[I]sibling\f[] before \f[I]node\f[]\&.  Returns 1 on success, 0 on failure.
 
-
+.PP
 \fIint\f[] \fBcmark_node_insert_after\f[](\fIcmark_node *node\f[], \fIcmark_node *sibling\f[])
 
+.PP
+Inserts \f[I]sibling\f[] after \f[I]node\f[]\&. Returns 1 on success, 0 on failure.
 
-
+.PP
 \fIint\f[] \fBcmark_node_prepend_child\f[](\fIcmark_node *node\f[], \fIcmark_node *child\f[])
 
+.PP
+Adds \f[I]child\f[] to the beginning of the children of \f[I]node\f[]\&.
+Returns 1 on success, 0 on failure.
 
-
+.PP
 \fIint\f[] \fBcmark_node_append_child\f[](\fIcmark_node *node\f[], \fIcmark_node *child\f[])
 
-
+.PP
+Adds \f[I]child\f[] to the end of the children of \f[I]node\f[]\&.
+Returns 1 on success, 0 on failure.
 
 .SS
 Parsing
+.PP
+Simple interface:
+.IP
+.nf
+\f[C]
+cmark_node *document = cmark_parse_document("Hello *world*", 12);
+\f[]
+.fi
+.PP
+Streaming interface:
+.IP
+.nf
+\f[C]
+cmark_parser *parser = cmark_parser_new();
+FILE *fp = fopen("myfile.md", "r");
+while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) {
+       cmark_parser_feed(parser, buffer, bytes);
+       if (bytes < sizeof(buffer)) {
+           break;
+       }
+}
+document = cmark_parser_finish(parser);
+cmark_parser_free(parser);
+\f[]
+.fi
 
+.PP
 \fIcmark_parser *\f[] \fBcmark_parser_new\f[](\fI\f[])
 
+.PP
+Creates a new parser object.
 
-
+.PP
 \fIvoid\f[] \fBcmark_parser_free\f[](\fIcmark_parser *parser\f[])
 
+.PP
+Frees memory allocated for a parser object.
 
-
-\fIcmark_node *\f[] \fBcmark_parser_finish\f[](\fIcmark_parser *parser\f[])
-
-
-
+.PP
 \fIvoid\f[] \fBcmark_parser_feed\f[](\fIcmark_parser *parser\f[], \fIconst char *buffer\f[], \fIsize_t len\f[])
 
+.PP
+Feeds a string of length \f[I]len\f[] to \f[I]parser\f[]\&.
 
+.PP
+\fIcmark_node *\f[] \fBcmark_parser_finish\f[](\fIcmark_parser *parser\f[])
 
-\fIcmark_node *\f[] \fBcmark_parse_document\f[](\fIconst char *buffer\f[], \fIsize_t len\f[])
+.PP
+Finish parsing and return a pointer to a tree of nodes.
 
+.PP
+\fIcmark_node *\f[] \fBcmark_parse_document\f[](\fIconst char *buffer\f[], \fIsize_t len\f[])
 
+.PP
+Parse a CommonMark document in \f[I]buffer\f[] of length \f[I]len\f[]\&.
+Returns a pointer to a tree of nodes.
 
+.PP
 \fIcmark_node *\f[] \fBcmark_parse_file\f[](\fIFILE *f\f[])
 
-
+.PP
+Parse a CommonMark document in file \f[I]f\f[], returning a pointer to
+a tree of nodes.
 
 .SS
 Rendering
 
+.PP
 \fIchar *\f[] \fBcmark_render_ast\f[](\fIcmark_node *root\f[])
 
+.PP
+Render a \f[I]node\f[] tree for debugging purposes, showing
+the hierachy of nodes and their types and contents.
 
-
+.PP
 \fIchar *\f[] \fBcmark_render_html\f[](\fIcmark_node *root\f[])
 
+.PP
+Render a \f[I]node\f[] tree as an HTML fragment.  It is up to the user
+to add an appropriate header and footer.
 
-
+.PP
 \fIchar *\f[] \fBcmark_render_man\f[](\fIcmark_node *root\f[])
 
-
+.PP
+Render a \f[I]node\f[] tree as a groff man page, without the header.
 
 .SH
 AUTHORS
diff --git a/src/cmark.h b/src/cmark.h
index 85dffa4..9de1037 100644
--- a/src/cmark.h
+++ b/src/cmark.h
@@ -91,12 +91,14 @@ typedef enum {
  * ## Creating and Destroying Nodes
  */
 
-/**
+/** Creates a new node of type 'type'.  Note that the node may have
+ * other required properties, which it is the caller's responsibility
+ * to assign.
  */
 CMARK_EXPORT cmark_node*
 cmark_node_new(cmark_node_type type);
 
-/**
+/** Frees the memory allocated for a node.
  */
 CMARK_EXPORT void
 cmark_node_free(cmark_node *node);
@@ -105,52 +107,83 @@ cmark_node_free(cmark_node *node);
  * ## Tree Traversal
  */
 
+/** Returns the next node in the sequence after 'node', or NULL if
+ * there is none.
+ */
 CMARK_EXPORT cmark_node*
 cmark_node_next(cmark_node *node);
 
-/**
+/** Returns the previous node in the sequence after 'node', or NULL if
+ * there is none.
  */
 CMARK_EXPORT cmark_node*
 cmark_node_previous(cmark_node *node);
 
-/**
+/** Returns the parent of 'node', or NULL if there is none.
  */
 CMARK_EXPORT cmark_node*
 cmark_node_parent(cmark_node *node);
 
-/**
+/** Returns the first child of 'node', or NULL if 'node' has no children.
  */
 CMARK_EXPORT cmark_node*
 cmark_node_first_child(cmark_node *node);
 
-/**
+/** Returns the last child of 'node', or NULL if 'node' has no children.
  */
 CMARK_EXPORT cmark_node*
 cmark_node_last_child(cmark_node *node);
 
 /**
  * ## Iterator
+ *
+ * An iterator will walk through a tree of nodes, starting from a root
+ * node, returning one node at a time, together with information about
+ * whether the node is being entered or exited.  The iterator will
+ * first descend to a child node, if there is one.  When there is no
+ * child, the iterator will go to the next sibling.  When there is no
+ * next sibling, the iterator will return to the parent (but with
+ * a 'cmark_event_type' of `CMARK_EVENT_EXIT`).  The iterator will
+ * return `CMARK_EVENT_DONE` when it reaches the root node again.
+ * One natural application is an HTML renderer, where an `ENTER` event
+ * outputs an open tag and an `EXIT` event outputs a close tag.
+ * An iterator might also be used to transform an AST in some systematic
+ * way, for example, turning all level-3 headers into regular paragraphs.
+ *
+ *     void
+ *     usage_example(cmark_node *root) {
+ *         cmark_event_type ev_type;
+ *         cmark_iter *iter = cmark_iter_new(root);
+ *
+ *         while ((ev_type = cmark_iter_next(iter)) != CMARK_EVENT_DONE) {
+ *             cmark_node *cur = cmark_iter_get_node(iter);
+ *             // Do something with `cur` and `ev_type`
+ *         }
+ *
+ *         cmark_iter_free(iter);
+ *     }
  */
 
-/**
+/** Creates a new iterator starting at 'root'.
  */
 CMARK_EXPORT
 cmark_iter*
 cmark_iter_new(cmark_node *root);
 
-/**
+/** Frees the memory allocated for an iterator.
  */
 CMARK_EXPORT
 void
 cmark_iter_free(cmark_iter *iter);
 
-/**
+/** Returns the event type (`CMARK_EVENT_ENTER`, `CMARK_EVENT_EXIT`,
+ * or `CMARK_EVENT_DONE`) for the next node.
  */
 CMARK_EXPORT
 cmark_event_type
 cmark_iter_next(cmark_iter *iter);
 
-/**
+/** Returns the next node in the sequence described above.
  */
 CMARK_EXPORT
 cmark_node*
@@ -160,102 +193,108 @@ cmark_iter_get_node(cmark_iter *iter);
  * ## Accessors
  */
 
-/**
+/** Returns the type of 'node', or `CMARK_NODE_NONE` on error.
  */
 CMARK_EXPORT cmark_node_type
 cmark_node_get_type(cmark_node *node);
 
-/**
+/** Returns the string contents of 'node', or NULL if none.
  */
 CMARK_EXPORT const char*
 cmark_node_get_string_content(cmark_node *node);
 
-/**
+/** Sets the string contents of 'node'.  Returns 1 on success,
+ * 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_set_string_content(cmark_node *node, const char *content);
 
-/**
+/** Returns the header level of 'node', or 0 if 'node' is not a header.
  */
 CMARK_EXPORT int
 cmark_node_get_header_level(cmark_node *node);
 
-/**
+/** Sets the header level of 'node', returning 1 on success and 0 on error.
  */
 CMARK_EXPORT int
 cmark_node_set_header_level(cmark_node *node, int level);
 
-/**
+/** Returns the list type of 'node', or `CMARK_NO_LIST` if 'node'
+ * is not a list.
  */
 CMARK_EXPORT cmark_list_type
 cmark_node_get_list_type(cmark_node *node);
 
-/**
+/** Sets the list type of 'node', returning 1 on success and 0 on error.
  */
 CMARK_EXPORT int
 cmark_node_set_list_type(cmark_node *node, cmark_list_type type);
 
-/**
+/** Returns starting number of 'node', if it is an ordered list, otherwise 0.
  */
 CMARK_EXPORT int
 cmark_node_get_list_start(cmark_node *node);
 
-/**
+/** Sets starting number of 'node', if it is an ordered list. Returns 1
+ * on success, 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_set_list_start(cmark_node *node, int start);
 
-/**
+/** Returns 1 if 'node' is a tight list, 0 otherwise.
  */
 CMARK_EXPORT int
 cmark_node_get_list_tight(cmark_node *node);
 
-/**
+/** Sets the "tightness" of a list.  Returns 1 on success, 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_set_list_tight(cmark_node *node, int tight);
 
-/**
+/** Returns the info string from a fenced code block, or NULL if none.
  */
 CMARK_EXPORT const char*
 cmark_node_get_fence_info(cmark_node *node);
 
-/**
+/** Sets the info string in a fenced code block, returning 1 on
+ * success and 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_set_fence_info(cmark_node *node, const char *info);
 
-/**
+/** Gets the URL of a link or image 'node', or NULL if none.
  */
 CMARK_EXPORT const char*
 cmark_node_get_url(cmark_node *node);
 
-/**
+/** Sets the URL of a link or image 'node'. Returns 1 on success,
+ * 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_set_url(cmark_node *node, const char *url);
 
-/**
+/** Gets the title of a link or image 'node', or NULL if none.
  */
 CMARK_EXPORT const char*
 cmark_node_get_title(cmark_node *node);
 
-/**
+/** Sets the title of a link or image 'node'. Returns 1 on success,
+ * 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_set_title(cmark_node *node, const char *title);
 
-/**
+/** Returns the line on which 'node' begins.
  */
 CMARK_EXPORT int
 cmark_node_get_start_line(cmark_node *node);
 
-/**
+/** Returns the column at which 'node' begins.
  */
 CMARK_EXPORT int
 cmark_node_get_start_column(cmark_node *node);
 
-/**
+/** Returns the line on which 'node' ends.
  */
 CMARK_EXPORT int
 cmark_node_get_end_line(cmark_node *node);
@@ -264,61 +303,83 @@ cmark_node_get_end_line(cmark_node *node);
  * ## Tree Manipulation
  */
 
-/**
+/** Unlinks a 'node', removing it from the tree, but not freeing its
+ * memory.  (Use 'cmark_node_free' for that.)
  */
 CMARK_EXPORT void
 cmark_node_unlink(cmark_node *node);
 
-/**
+/** Inserts 'sibling' before 'node'.  Returns 1 on success, 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_insert_before(cmark_node *node, cmark_node *sibling);
 
-/**
+/** Inserts 'sibling' after 'node'. Returns 1 on success, 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_insert_after(cmark_node *node, cmark_node *sibling);
 
-/**
+/** Adds 'child' to the beginning of the children of 'node'.
+ * Returns 1 on success, 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_prepend_child(cmark_node *node, cmark_node *child);
 
-/**
+/** Adds 'child' to the end of the children of 'node'.
+ * Returns 1 on success, 0 on failure.
  */
 CMARK_EXPORT int
 cmark_node_append_child(cmark_node *node, cmark_node *child);
 
 /**
  * ## Parsing
+ *
+ * Simple interface:
+ *
+ *     cmark_node *document = cmark_parse_document("Hello *world*", 12);
+ *
+ * Streaming interface:
+ *
+ *     cmark_parser *parser = cmark_parser_new();
+ *     FILE *fp = fopen("myfile.md", "r");
+ *     while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) {
+ *     	   cmark_parser_feed(parser, buffer, bytes);
+ *     	   if (bytes < sizeof(buffer)) {
+ *     	       break;
+ *     	   }
+ *     }
+ *     document = cmark_parser_finish(parser);
+ *     cmark_parser_free(parser);
  */
 
-/**
+/** Creates a new parser object.
  */
 CMARK_EXPORT
 cmark_parser *cmark_parser_new();
 
-/**
+/** Frees memory allocated for a parser object.
  */
 CMARK_EXPORT
 void cmark_parser_free(cmark_parser *parser);
 
-/**
+/** Feeds a string of length 'len' to 'parser'.
  */
 CMARK_EXPORT
-cmark_node *cmark_parser_finish(cmark_parser *parser);
+void cmark_parser_feed(cmark_parser *parser, const char *buffer, size_t len);
 
-/**
+/** Finish parsing and return a pointer to a tree of nodes.
  */
 CMARK_EXPORT
-void cmark_parser_feed(cmark_parser *parser, const char *buffer, size_t len);
+cmark_node *cmark_parser_finish(cmark_parser *parser);
 
-/**
+/** Parse a CommonMark document in 'buffer' of length 'len'.
+ * Returns a pointer to a tree of nodes.
  */
 CMARK_EXPORT
 cmark_node *cmark_parse_document(const char *buffer, size_t len);
 
-/**
+/** Parse a CommonMark document in file 'f', returning a pointer to
+ * a tree of nodes.
  */
 CMARK_EXPORT
 cmark_node *cmark_parse_file(FILE *f);
@@ -327,17 +388,19 @@ cmark_node *cmark_parse_file(FILE *f);
  * ## Rendering
  */
 
-/**
+/** Render a 'node' tree for debugging purposes, showing
+ * the hierachy of nodes and their types and contents.
  */
 CMARK_EXPORT
 char *cmark_render_ast(cmark_node *root);
 
-/**
+/** Render a 'node' tree as an HTML fragment.  It is up to the user
+ * to add an appropriate header and footer.
  */
 CMARK_EXPORT
 char *cmark_render_html(cmark_node *root);
 
-/**
+/** Render a 'node' tree as a groff man page, without the header.
  */
 CMARK_EXPORT
 char *cmark_render_man(cmark_node *root);