docs: refine Contact::get_verifier_id and Contact::is_verified documentation (#4922)

Co-authored-by: link2xt <link2xt@testrun.org>

deltachat-ffi/deltachat.h

@@ -5033,10 +5033,18 @@ int             dc_contact_is_blocked        (const dc_contact_t* contact);
 
 
 /**
- * Check if a contact was verified. E.g. by a secure-join QR code scan
- * and if the key has not changed since this verification.
+ * Check if the contact
+ * can be added to verified chats,
+ * i.e. has a verified key
+ * and Autocrypt key matches the verified key.
  *
- * The UI may draw a checkbox or something like that beside verified contacts.
+ * If contact is verified
+ * UI should display green checkmark after the contact name
+ * in the title of the contact profile,
+ * in contact list items and in chat member list items.
+ *
+ * Do not use this function when displaying profile view contents.
+ * Use dc_contact_get_verifier_id instead.
  *
  * @memberof dc_contact_t
  * @param contact The contact object.
@@ -5069,9 +5077,18 @@ char*           dc_contact_get_verifier_addr       (dc_contact_t* contact);
 
 
 /**
- * Return the `ContactId` that verified a contact
+ * Return the contact ID that verified a contact.
  *
- * The UI may use this in addition to a checkmark showing the verification status
+ * 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.
+ *
+ * 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.
  *
  * @memberof dc_contact_t
  * @param contact The contact object.

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

@@ -19,11 +19,27 @@ pub struct ContactObject {
     profile_image: Option<String>, // BLOBS
     name_and_addr: String,
     is_blocked: bool,
+
+    /// True if the contact can be added to verified groups.
+    ///
+    /// If this is true
+    /// UI should display green checkmark after the contact name
+    /// in the title of the contact profile,
+    /// in contact list items and in chat member list items.
     is_verified: bool,
-    /// the address that verified this contact
+
+    /// The address that verified this contact
+    ///
+    /// Deprecated, use `verifier_id` instead.
     verifier_addr: Option<String>,
-    /// the id of the contact that verified this contact
+
+    /// The ID of the contact that verified this contact.
+    ///
+    /// If this is present,
+    /// display a green checkmark and "Introduced by ..."
+    /// string followed by the verifier contact name and address.
     verifier_id: Option<u32>,
+
     /// the contact's last seen timestamp
     last_seen: i64,
     was_seen_recently: bool,

src/contact.rs

@@ -1251,10 +1251,18 @@ impl Contact {
         self.status.as_str()
     }
 
-    /// Check if a contact was verified. E.g. by a secure-join QR code scan
-    /// and if the key has not changed since this verification.
+    /// Returns true if the contact
+    /// can be added to verified chats,
+    /// i.e. has a verified key
+    /// and Autocrypt key matches the verified key.
     ///
-    /// The UI may draw a checkbox or something like that beside verified contacts.
+    /// If contact is verified
+    /// UI should display green checkmark after the contact name
+    /// in the title of the contact profile,
+    /// in contact list items and in chat member list items.
+    ///
+    /// Do not use this function when displaying profile view contents.
+    /// Use [Self::get_verifier_id] instead.
     pub async fn is_verified(&self, context: &Context) -> Result<VerifiedStatus> {
         // We're always sort of secured-verified as we could verify the key on this device any time with the key
         // on this device
@@ -1272,13 +1280,26 @@ impl Contact {
     }
 
     /// Returns the address that verified the contact.
+    ///
+    /// Deprecated, use [Self::get_verifier_id] instead.
     pub async fn get_verifier_addr(&self, context: &Context) -> Result<Option<String>> {
         Ok(Peerstate::from_addr(context, self.get_addr())
             .await?
             .and_then(|peerstate| peerstate.get_verifier().map(|addr| addr.to_owned())))
     }
 
-    /// Returns the ContactId that verified the contact.
+    /// Returns the `ContactId` that verified the 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 [Self::get_name_n_addr].
+    ///
+    /// If this function returns a verifier,
+    /// this does not necessarily mean
+    /// you can add the contact to verified chats.
+    /// Use [Self::is_verified] to check
+    /// if a contact can be added to a verified chat instead.
     pub async fn get_verifier_id(&self, context: &Context) -> Result<Option<ContactId>> {
         let Some(verifier_addr) = self.get_verifier_addr(context).await? else {
             return Ok(None);