From c5fb1416bde392af335ad62374db709fd9241549 Mon Sep 17 00:00:00 2001
From: Torsten Grote <t@grobox.de>
Date: Mon, 16 Jan 2023 10:30:32 -0300
Subject: [PATCH] Update JavaDoc for SharingState change

---
 .../invitation/GroupInvitationManager.java    |  6 ++--
 .../briar/api/sharing/SharingManager.java     | 32 +++++++++++++++++--
 2 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/briar-api/src/main/java/org/briarproject/briar/api/privategroup/invitation/GroupInvitationManager.java b/briar-api/src/main/java/org/briarproject/briar/api/privategroup/invitation/GroupInvitationManager.java
index 201835ca4..fc0feb5b0 100644
--- a/briar-api/src/main/java/org/briarproject/briar/api/privategroup/invitation/GroupInvitationManager.java
+++ b/briar-api/src/main/java/org/briarproject/briar/api/privategroup/invitation/GroupInvitationManager.java
@@ -80,8 +80,10 @@ public interface GroupInvitationManager extends ConversationClient {
 	Collection<GroupInvitationItem> getInvitations() throws DbException;
 
 	/**
-	 * Returns true if the given contact can be invited to the given private
-	 * group.
+	 * Returns the current {@link SharingStatus} for the given {@link Contact}
+	 * and {@link PrivateGroup} identified by the given {@link GroupId}.
+	 * This indicates whether the {@link PrivateGroup} can be shared
+	 * with the contact.
 	 */
 	SharingStatus getSharingStatus(Contact c, GroupId g) throws DbException;
 }
diff --git a/briar-api/src/main/java/org/briarproject/briar/api/sharing/SharingManager.java b/briar-api/src/main/java/org/briarproject/briar/api/sharing/SharingManager.java
index b71f23da3..aa0e5202f 100644
--- a/briar-api/src/main/java/org/briarproject/briar/api/sharing/SharingManager.java
+++ b/briar-api/src/main/java/org/briarproject/briar/api/sharing/SharingManager.java
@@ -18,7 +18,27 @@ public interface SharingManager<S extends Shareable>
 		extends ConversationClient {
 
 	enum SharingStatus {
-		SHAREABLE, INVITED, SHARING, NOT_SUPPORTED
+		/**
+		 * The {@link Shareable} can be shared with the requested contact.
+		 */
+		SHAREABLE,
+		/**
+		 * The {@link Shareable} can not be shared with the requested contact,
+		 * because of an ongoing sharing session.
+		 * In most cases, this means that the contact was already invited.
+		 */
+		INVITED,
+		/**
+		 * The {@link Shareable} can not be shared with the requested contact,
+		 * because it is already being shared.
+		 */
+		SHARING,
+		/**
+		 * The {@link Shareable} can not be shared with the requested contact,
+		 * because it is not supported by that contact.
+		 * This could be a missing or outdated client.
+		 */
+		NOT_SUPPORTED
 	}
 
 	/**
@@ -82,12 +102,18 @@ public interface SharingManager<S extends Shareable>
 			throws DbException;
 
 	/**
-	 * Returns true if the group not already shared and no invitation is open
+	 * Returns the current {@link SharingStatus} for the given {@link Contact}
+	 * and {@link Shareable} identified by the given {@link GroupId}.
+	 * This indicates whether the {@link Shareable} can be shared
+	 * with the contact.
 	 */
 	SharingStatus getSharingStatus(GroupId g, Contact c) throws DbException;
 
 	/**
-	 * Returns true if the group not already shared and no invitation is open
+	 * Returns the current {@link SharingStatus} for the given {@link Contact}
+	 * and {@link Shareable} identified by the given {@link GroupId}.
+	 * This indicates whether the {@link Shareable} can be shared
+	 * with the contact.
 	 */
 	SharingStatus getSharingStatus(Transaction txn, GroupId g, Contact c)
 			throws DbException;