From f9073827f0e8d9b10fa43852a1f981eda44140c8 Mon Sep 17 00:00:00 2001
From: John MacFarlane <jgm@berkeley.edu>
Date: Fri, 2 Jun 2017 16:41:06 +0200
Subject: Document cases where get_ functions return NULL.

E.g. cmark_node_get_url on a non-link or image.
Closes #155.
---
 man/man3/cmark.3 | 17 +++++++++++------
 src/cmark.h      | 15 ++++++++++-----
 2 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/man/man3/cmark.3 b/man/man3/cmark.3
index 5f7fcc6..c04e442 100644
--- a/man/man3/cmark.3
+++ b/man/man3/cmark.3
@@ -1,4 +1,4 @@
-.TH cmark 3 "May 05, 2017" "LOCAL" "Library Functions Manual"
+.TH cmark 3 "June 02, 2017" "LOCAL" "Library Functions Manual"
 .SH
 NAME
 .PP
@@ -331,7 +331,8 @@ of the type, or \f[C]"<unknown>"\f[].
 
 .PP
 Returns the string contents of \f[I]node\f[], or an empty string if none
-is set.
+is set. Returns NULL if called on a node that does not have string
+content.
 
 .PP
 \fIint\f[] \fBcmark_node_set_literal\f[](\fIcmark_node *node\f[], \fIconst char *content\f[])
@@ -426,7 +427,8 @@ and 0 on failure.
 
 .PP
 Returns the URL of a link or image \f[I]node\f[], or an empty string if
-no URL is set.
+no URL is set. Returns NULL if called on a node that is not a link or
+image.
 
 .PP
 \fIint\f[] \fBcmark_node_set_url\f[](\fIcmark_node *node\f[], \fIconst char *url\f[])
@@ -440,7 +442,8 @@ on failure.
 
 .PP
 Returns the title of a link or image \f[I]node\f[], or an empty string
-if no title is set.
+if no title is set. Returns NULL if called on a node that is not a link
+or image.
 
 .PP
 \fIint\f[] \fBcmark_node_set_title\f[](\fIcmark_node *node\f[], \fIconst char *title\f[])
@@ -454,7 +457,8 @@ on failure.
 
 .PP
 Returns the literal "on enter" text for a custom \f[I]node\f[], or an
-empty string if no on_enter is set.
+empty string if no on_enter is set. Returns NULL if called on a
+non\-custom node.
 
 .PP
 \fIint\f[] \fBcmark_node_set_on_enter\f[](\fIcmark_node *node\f[], \fIconst char *on_enter\f[])
@@ -469,7 +473,8 @@ success 0 on failure.
 
 .PP
 Returns the literal "on exit" text for a custom \f[I]node\f[], or an
-empty string if no on_exit is set.
+empty string if no on_exit is set. Returns NULL if called on a
+non\-custom node.
 
 .PP
 \fIint\f[] \fBcmark_node_set_on_exit\f[](\fIcmark_node *node\f[], \fIconst char *on_exit\f[])
diff --git a/src/cmark.h b/src/cmark.h
index 793fcf4..9f6e0c6 100644
--- a/src/cmark.h
+++ b/src/cmark.h
@@ -265,7 +265,8 @@ CMARK_EXPORT
 const char *cmark_node_get_type_string(cmark_node *node);
 
 /** Returns the string contents of 'node', or an empty
-    string if none is set.
+    string if none is set.  Returns NULL if called on a
+    node that does not have string content.
  */
 CMARK_EXPORT const char *cmark_node_get_literal(cmark_node *node);
 
@@ -334,7 +335,8 @@ CMARK_EXPORT const char *cmark_node_get_fence_info(cmark_node *node);
 CMARK_EXPORT int cmark_node_set_fence_info(cmark_node *node, const char *info);
 
 /** Returns the URL of a link or image 'node', or an empty string
-    if no URL is set.
+    if no URL is set.  Returns NULL if called on a node that is
+    not a link or image.
  */
 CMARK_EXPORT const char *cmark_node_get_url(cmark_node *node);
 
@@ -344,7 +346,8 @@ CMARK_EXPORT const char *cmark_node_get_url(cmark_node *node);
 CMARK_EXPORT int cmark_node_set_url(cmark_node *node, const char *url);
 
 /** Returns the title of a link or image 'node', or an empty
-    string if no title is set.
+    string if no title is set.  Returns NULL if called on a node
+    that is not a link or image.
  */
 CMARK_EXPORT const char *cmark_node_get_title(cmark_node *node);
 
@@ -354,7 +357,8 @@ CMARK_EXPORT const char *cmark_node_get_title(cmark_node *node);
 CMARK_EXPORT int cmark_node_set_title(cmark_node *node, const char *title);
 
 /** Returns the literal "on enter" text for a custom 'node', or
-    an empty string if no on_enter is set.
+    an empty string if no on_enter is set.  Returns NULL if called
+    on a non-custom node.
  */
 CMARK_EXPORT const char *cmark_node_get_on_enter(cmark_node *node);
 
@@ -366,7 +370,8 @@ CMARK_EXPORT int cmark_node_set_on_enter(cmark_node *node,
                                          const char *on_enter);
 
 /** Returns the literal "on exit" text for a custom 'node', or
-    an empty string if no on_exit is set.
+    an empty string if no on_exit is set.  Returns NULL if
+    called on a non-custom node.
  */
 CMARK_EXPORT const char *cmark_node_get_on_exit(cmark_node *node);
 
-- 
cgit v1.2.3