From ec910f84433561f59141c7bf88dd5c9a93879aa6 Mon Sep 17 00:00:00 2001
From: "B. Petersen" <r10s@b44t.com>
Date: Mon, 8 Oct 2018 10:41:58 +0200
Subject: [PATCH] comment some behaviours or NULL arguments and NULL return
 values

---
 src/dc_array.c    | 4 +++-
 src/dc_chat.c     | 5 ++++-
 src/dc_chatlist.c | 6 ++++--
 src/dc_contact.c  | 1 +
 src/dc_context.c  | 1 +
 src/dc_lot.c      | 1 +
 src/dc_msg.c      | 5 ++++-
 7 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/src/dc_array.c b/src/dc_array.c
index 9028da14..c59e26d3 100644
--- a/src/dc_array.c
+++ b/src/dc_array.c
@@ -60,7 +60,9 @@ dc_array_t* dc_array_new(dc_context_t* context, size_t initsize)
  * Free an array object. Does not free any data items.
  *
  * @memberof dc_array_t
- * @param array The array object to free, created eg. by dc_get_chatlist(), dc_get_contacts() and so on.
+ * @param array The array object to free,
+ *     created eg. by dc_get_chatlist(), dc_get_contacts() and so on.
+ *     If NULL is given, nothing is done.
  * @return None.
  */
 void dc_array_unref(dc_array_t* array)
diff --git a/src/dc_chat.c b/src/dc_chat.c
index b83ad035..78f0889e 100644
--- a/src/dc_chat.c
+++ b/src/dc_chat.c
@@ -61,6 +61,7 @@ dc_chat_t* dc_chat_new(dc_context_t* context)
  *
  * @memberof dc_chat_t
  * @param chat Chat object are returned eg. by dc_get_chat().
+ *     If NULL is given, nothing is done.
  * @return None.
  */
 void dc_chat_unref(dc_chat_t* chat)
@@ -540,7 +541,9 @@ int dc_add_to_chat_contacts_table(dc_context_t* context, uint32_t chat_id, uint3
  * @memberof dc_context_t
  * @param context The context object as returned from dc_context_new().
  * @param chat_id The ID of the chat to get the chat object for.
- * @return A chat object of the type dc_chat_t, must be freed using dc_chat_unref() when done.
+ * @return A chat object of the type dc_chat_t,
+ *     must be freed using dc_chat_unref() when done.
+ *     On errors, NULL is returned.
  */
 dc_chat_t* dc_get_chat(dc_context_t* context, uint32_t chat_id)
 {
diff --git a/src/dc_chatlist.c b/src/dc_chatlist.c
index 49f573b9..431944c8 100644
--- a/src/dc_chatlist.c
+++ b/src/dc_chatlist.c
@@ -56,6 +56,7 @@ dc_chatlist_t* dc_chatlist_new(dc_context_t* context)
  *
  * @memberof dc_chatlist_t
  * @param chatlist The chatlist object to free, created eg. by dc_get_chatlist(), dc_search_msgs().
+ *     If NULL is given, nothing is done.
  * @return None.
  */
 void dc_chatlist_unref(dc_chatlist_t* chatlist)
@@ -456,8 +457,9 @@ int dc_get_archived_cnt(dc_context_t* context)
  *     are returned.  Give NULL for no filtering.
  * @param query_id An optional contact ID for filtering the list.  Only chats including this contact ID
  *     are returned.  Give 0 for no filtering.
- * @return A chatlist as an dc_chatlist_t object. Must be freed using
- *     dc_chatlist_unref() when no longer used.
+ * @return A chatlist as an dc_chatlist_t object.
+ *     On errors, NULL is returned.
+ *     Must be freed using dc_chatlist_unref() when no longer used.
  *
  * See also: dc_get_chat_msgs() to get the messages of a single chat.
  */
diff --git a/src/dc_contact.c b/src/dc_contact.c
index e8193bda..73de58e8 100644
--- a/src/dc_contact.c
+++ b/src/dc_contact.c
@@ -58,6 +58,7 @@ dc_contact_t* dc_contact_new(dc_context_t* context)
  *
  * @memberof dc_contact_t
  * @param contact The contact object as created eg. by dc_get_contact().
+ *     If NULL is given, nothing is done.
  * @return None.
  */
 void dc_contact_unref(dc_contact_t* contact)
diff --git a/src/dc_context.c b/src/dc_context.c
index 54623236..3db5d759 100644
--- a/src/dc_context.c
+++ b/src/dc_context.c
@@ -154,6 +154,7 @@ dc_context_t* dc_context_new(dc_callback_t cb, void* userdata, const char* os_na
  *
  * @memberof dc_context_t
  * @param context The context object as created by dc_context_new().
+ *     If NULL is given, nothing is done.
  * @return None.
  */
 void dc_context_unref(dc_context_t* context)
diff --git a/src/dc_lot.c b/src/dc_lot.c
index 50a980f9..edd0388c 100644
--- a/src/dc_lot.c
+++ b/src/dc_lot.c
@@ -49,6 +49,7 @@ dc_lot_t* dc_lot_new()
  *
  * @memberof dc_lot_t
  * @param set The object to free.
+ *     If NULL is given, nothing is done.
  * @return None.
  */
 void dc_lot_unref(dc_lot_t* set)
diff --git a/src/dc_msg.c b/src/dc_msg.c
index d0222349..a6ae3936 100644
--- a/src/dc_msg.c
+++ b/src/dc_msg.c
@@ -71,6 +71,7 @@ dc_msg_t* dc_msg_new_untyped(dc_context_t* context)
  *
  * @memberof dc_msg_t
  * @param msg The message object to free.
+ *     If NULL is given, nothing is done.
  * @return None.
  */
 void dc_msg_unref(dc_msg_t* msg)
@@ -1434,7 +1435,9 @@ void dc_update_server_uid(dc_context_t* context, const char* rfc724_mid, const c
  * @memberof dc_context_t
  * @param context The context as created by dc_context_new().
  * @param msg_id The message ID for which the message object should be created.
- * @return A dc_msg_t message object. When done, the object must be freed using dc_msg_unref()
+ * @return A dc_msg_t message object.
+ *     On errors, NULL is returned.
+ *     When done, the object must be freed using dc_msg_unref().
  */
 dc_msg_t* dc_get_msg(dc_context_t* context, uint32_t msg_id)
 {