docs: clarify the meaning of is_verified() vs verifier_id() (#7027)

this PR adapts the documentation UI guidance to recent "green checkmark"
discussions

cmp deltachat/deltachat-pages#1145,
deltachat/deltachat-ios#2781,
deltachat/deltachat-android#3828,
deltachat/deltachat-desktop#5318

---------

Co-authored-by: Hocuri <[email protected]>

Author: r10s

deltachat-ffi/deltachat.h

@@ -3818,12 +3818,6 @@ int             dc_chat_can_send              (const dc_chat_t* chat);
  * Protected chats are created using dc_create_group_chat()
  * by setting the 'protect' parameter to 1.
  *
- * UI should display a green checkmark
- * in the chat title,
- * in the chatlist item
- * and in the chat profile
- * if chat protection is enabled.
- *
  * @memberof dc_chat_t
  * @param chat The chat object.
  * @return 1=chat protected, 0=chat is not protected.
@@ -5259,20 +5253,14 @@ int             dc_contact_is_blocked        (const dc_contact_t* contact);
 
 /**
  * Check if the contact
- * can be added to verified chats,
- * i.e. has a verified key
- * and Autocrypt key matches the verified key.
+ * can be added to protected chats.
  *
- * If contact is verified
- * UI should display green checkmark after the contact name
- * in contact list items,
- * in chat member list items
- * and in profiles if no chat with the contact exist (otherwise, use dc_chat_is_protected()).
+ * See dc_contact_get_verifier_id() for a guidance how to display these information.
  *
  * @memberof dc_contact_t
  * @param contact The contact object.
  * @return 0: contact is not verified.
- *    2: SELF and contact have verified their fingerprints in both directions; in the UI typically checkmarks are shown.
+ *    2: SELF and contact have verified their fingerprints in both directions.
  */
 int             dc_contact_is_verified       (dc_contact_t* contact);
 
@@ -5303,16 +5291,22 @@ int             dc_contact_is_key_contact    (dc_contact_t* contact);
 /**
  * Return the contact ID that verified a contact.
  *
- * If the function returns non-zero result,
- * display green checkmark in the profile and "Introduced by ..." line
- * with the name and address of the contact
- * formatted by dc_contact_get_name_n_addr.
+ * As verifier may be unknown,
+ * use dc_contact_is_verified() to check if a contact can be added to a protected chat.
+ *
+ * UI should display the information in the contact's profile as follows:
+ *
+ * - If dc_contact_get_verifier_id() != 0,
+ *   display text "Introduced by ..."
+ *   with the name and address of the contact
+ *   formatted by dc_contact_get_name_n_addr().
+ *   Prefix the text by a green checkmark.
+ *
+ * - If dc_contact_get_verifier_id() == 0 and dc_contact_is_verified() != 0,
+ *   display "Introduced" prefixed by a green checkmark.
  *
- * If this function returns a verifier,
- * this does not necessarily mean
- * you can add the contact to verified chats.
- * Use dc_contact_is_verified() to check
- * if a contact can be added to a verified chat instead.
+ * - if dc_contact_get_verifier_id() == 0 and dc_contact_is_verified() == 0,
+ *   display nothing
  *
  * @memberof dc_contact_t
  * @param contact The contact object.
@@ -6378,7 +6372,6 @@ void dc_event_unref(dc_event_t* event);
 
 /**
  * Chat changed. The name or the image of a chat group was changed or members were added or removed.
- * Or the verify state of a chat has changed.
  * See dc_set_chat_name(), dc_set_chat_profile_image(), dc_add_contact_to_chat()
  * and dc_remove_contact_from_chat().
  *

deltachat-jsonrpc/src/api/types/chat.rs

@@ -21,15 +21,16 @@ pub struct FullChat {
 
     /// True if the chat is protected.
     ///
-    /// UI should display a green checkmark
-    /// in the chat title,
-    /// in the chat profile title and
-    /// in the chatlist item
-    /// if chat protection is enabled.
-    /// UI should also display a green checkmark
-    /// in the contact profile
-    /// if 1:1 chat with this contact exists and is protected.
+    /// Only verified contacts
+    /// as determined by [`ContactObject::is_verified`] / `Contact.isVerified`
+    /// can be added to protected chats.
+    ///
+    /// Protected chats are created using [`create_group_chat`] / `createGroupChat()`
+    /// by setting the 'protect' parameter to true.
+    ///
+    /// [`create_group_chat`]: crate::api::CommandApi::create_group_chat
     is_protected: bool,
+
     /// True if the chat is encrypted.
     /// This means that all messages in the chat are encrypted,
     /// and all contacts in the chat are "key-contacts",

deltachat-jsonrpc/src/api/types/contact.rs

@@ -31,13 +31,11 @@ pub struct ContactObject {
     /// e.g. if we just scanned the fingerprint from a QR code.
     e2ee_avail: bool,
 
-    /// True if the contact can be added to verified groups.
+    /// True if the contact
+    /// can be added to protected chats
+    /// because SELF and contact have verified their fingerprints in both directions.
     ///
-    /// If this is true
-    /// UI should display green checkmark after the contact name
-    /// in contact list items,
-    /// in chat member list items
-    /// and in profiles if no chat with the contact exist.
+    /// See [`Self::verifier_id`]/`Contact.verifierId` for a guidance how to display these information.
     is_verified: bool,
 
     /// True if the contact profile title should have a green checkmark.
@@ -46,12 +44,29 @@ pub struct ContactObject {
     /// or will have a green checkmark if created.
     is_profile_verified: bool,
 
-    /// The ID of the contact that verified this contact.
+    /// The contact ID that verified a contact.
     ///
-    /// If this is present,
-    /// display a green checkmark and "Introduced by ..."
-    /// string followed by the verifier contact name and address
-    /// in the contact profile.
+    /// As verifier may be unknown,
+    /// use [`Self::is_verified`]/`Contact.isVerified` to check if a contact can be added to a protected chat.
+    ///
+    /// UI should display the information in the contact's profile as follows:
+    ///
+    /// - If `verifierId` != 0,
+    ///   display text "Introduced by ..."
+    ///   with the name and address of the contact
+    ///   formatted by `name_and_addr`/`nameAndAddr`.
+    ///   Prefix the text by a green checkmark.
+    ///
+    /// - If `verifierId` == 0 and `isVerified` != 0,
+    ///   display "Introduced" prefixed by a green checkmark.
+    ///
+    /// - if `verifierId` == 0 and `isVerified` == 0,
+    ///   display nothing
+    ///
+    /// This contains the contact ID of the verifier.
+    /// If it is `DC_CONTACT_ID_SELF`, we verified the contact ourself.
+    /// If it is None/Null, we don't have verifier information or
+    /// the contact is not verified.
     verifier_id: Option<u32>,
 
     /// the contact's last seen timestamp

deltachat-jsonrpc/src/api/types/events.rs

@@ -224,7 +224,6 @@ pub enum EventType {
     },
 
     /// Chat changed.  The name or the image of a chat group was changed or members were added or removed.
-    /// Or the verify state of a chat has changed.
     /// See setChatName(), setChatProfileImage(), addContactToChat()
     /// and removeContactFromChat().
     ///