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

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

cmp https://github.com/deltachat/deltachat-pages/pull/1145,
https://github.com/deltachat/deltachat-ios/pull/2781,
https://github.com/deltachat/deltachat-android/pull/3828,
https://github.com/deltachat/deltachat-desktop/pull/5318

---------

Co-authored-by: Hocuri <hocuri@gmx.de>

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().
     ///