From 6cadefecaaa1a694406bd209e991192365497861 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20K=C3=BCrten?= <sebastian@mobanisto.de>
Date: Fri, 3 Dec 2021 13:40:03 +0100
Subject: [PATCH] Add documentation for ContactsManager methods
---
.../mailbox/core/contacts/ContactsManager.kt | 19 ++++++++++++++++---
1 file changed, 16 insertions(+), 3 deletions(-)
diff --git a/mailbox-core/src/main/java/org/briarproject/mailbox/core/contacts/ContactsManager.kt b/mailbox-core/src/main/java/org/briarproject/mailbox/core/contacts/ContactsManager.kt
index e4e9bd42..e511899e 100644
--- a/mailbox-core/src/main/java/org/briarproject/mailbox/core/contacts/ContactsManager.kt
+++ b/mailbox-core/src/main/java/org/briarproject/mailbox/core/contacts/ContactsManager.kt
@@ -29,7 +29,10 @@ class ContactsManager @Inject constructor(
}
/**
- * Used by owner to list contacts.
+ * Used by owner to list contacts managed by the mailbox.
+ *
+ * Checks if provided auth token is the owner.
+ * Responds with 200 (OK) with the list of contact IDs in JSON.
*/
suspend fun listContacts(call: ApplicationCall) {
authManager.assertIsOwner(call.principal())
@@ -42,7 +45,14 @@ class ContactsManager @Inject constructor(
}
/**
- * Used by owner to add new contacts.
+ * Used by owner to add a new contact to the mailbox.
+ *
+ * Briar generates 32 bytes of random data for bearer token, inboxId and outboxId, encodes
+ * them as hexadecimal strings and sends them along with its contactId.
+ *
+ * Checks if provided auth token is the owner.
+ * Responds with 201 (CREATED) for a successful POST. If the contactId is already in use,
+ * 409 (CONFLICT) is returned.
*/
suspend fun postContact(call: ApplicationCall) {
authManager.assertIsOwner(call.principal())
@@ -72,7 +82,10 @@ class ContactsManager @Inject constructor(
}
/**
- * Used by owner to add remove contacts.
+ * Used by owner to remove a contact.
+ *
+ * [paramContactId] is the integer contact ID the contact was added with.
+ * Returns 200 (OK) when deletion was successful.
*/
fun deleteContact(call: ApplicationCall, paramContactId: String) {
authManager.assertIsOwner(call.principal())
--
GitLab