From f8271ed0f523f61dae39b2c9edcda7758af2b84d Mon Sep 17 00:00:00 2001
From: John MacFarlane <jgm@berkeley.edu>
Date: Sat, 14 May 2016 12:33:29 -0700
Subject: Better documentation of memory-freeing responsibilities.

in cmark.h and its man page. Closes #124.
---
 man/man3/cmark.3 | 17 +++++++++++------
 src/cmark.h      | 14 ++++++++++----
 2 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/man/man3/cmark.3 b/man/man3/cmark.3
index 7808aa9..5642e59 100644
--- a/man/man3/cmark.3
+++ b/man/man3/cmark.3
@@ -1,4 +1,4 @@
-.TH cmark 3 "April 26, 2016" "LOCAL" "Library Functions Manual"
+.TH cmark 3 "May 14, 2016" "LOCAL" "Library Functions Manual"
 .SH
 NAME
 .PP
@@ -15,7 +15,8 @@ Simple Interface
 .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.
+null\-terminated, UTF\-8\-encoded string. It is the caller's
+responsibility to free the returned buffer.
 
 .SS
 Node Structure
@@ -224,8 +225,9 @@ typedef enum {
 
 .PP
 Creates a new iterator starting at \f[I]root\f[]. The current node and
-event type are undefined until \f[C]cmark_iter_next\f[] is called for
-the first time.
+event type are undefined until \f[I]cmark_iter_next\f[] is called for
+the first time. The memory allocated for the iterator should be released
+using \f[I]cmark_iter_free\f[] when it is no longer needed.
 
 .PP
 \fIvoid\f[] \fBcmark_iter_free\f[](\fIcmark_iter *iter\f[])
@@ -583,14 +585,17 @@ Finish parsing and return a pointer to a tree of nodes.
 
 .PP
 Parse a CommonMark document in \f[I]buffer\f[] of length \f[I]len\f[].
-Returns a pointer to a tree of nodes.
+Returns a pointer to a tree of nodes. The memory allocated for the node
+tree should be released using \f[I]cmark_node_free\f[] when it is no
+longer needed.
 
 .PP
 \fIcmark_node *\f[] \fBcmark_parse_file\f[](\fIFILE *f\f[], \fIint options\f[])
 
 .PP
 Parse a CommonMark document in file \f[I]f\f[], returning a pointer to a
-tree of nodes.
+tree of nodes. The memory allocated for the node tree should be released
+using \f[I]cmark_node_free\f[] when it is no longer needed.
 
 .SS
 Rendering
diff --git a/src/cmark.h b/src/cmark.h
index 2f4e603..911ceb7 100644
--- a/src/cmark.h
+++ b/src/cmark.h
@@ -21,7 +21,8 @@ extern "C" {
 
 /** Convert 'text' (assumed to be a UTF-8 encoded string with length
  * 'len') from CommonMark Markdown to HTML, returning a null-terminated,
- * UTF-8-encoded string.
+ * UTF-8-encoded string. It is the caller's responsibility
+ * to free the returned buffer.
  */
 CMARK_EXPORT
 char *cmark_markdown_to_html(const char *text, size_t len, int options);
@@ -179,7 +180,9 @@ typedef enum {
 } cmark_event_type;
 
 /** Creates a new iterator starting at 'root'.  The current node and event
- * type are undefined until `cmark_iter_next` is called for the first time.
+ * type are undefined until 'cmark_iter_next' is called for the first time.
+ * The memory allocated for the iterator should be released using
+ * 'cmark_iter_free' when it is no longer needed.
  */
 CMARK_EXPORT
 cmark_iter *cmark_iter_new(cmark_node *root);
@@ -450,13 +453,16 @@ CMARK_EXPORT
 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.
+ * Returns a pointer to a tree of nodes.  The memory allocated for
+ * the node tree should be released using 'cmark_node_free'
+ * when it is no longer needed.
  */
 CMARK_EXPORT
 cmark_node *cmark_parse_document(const char *buffer, size_t len, int options);
 
 /** Parse a CommonMark document in file 'f', returning a pointer to
- * a tree of nodes.
+ * a tree of nodes.  The memory allocated for the node tree should be
+ * released using 'cmark_node_free' when it is no longer needed.
  */
 CMARK_EXPORT
 cmark_node *cmark_parse_file(FILE *f, int options);
-- 
cgit v1.2.3