Merge pull request #360 from deltachat/comment

comment some behaviours or NULL arguments and NULL return values

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)

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)
 {

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.
  */

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)

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)

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)

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)
 {