Add full public interfaces

Signed-off-by: Julius Härtl <jus@bitgrid.net>

7 files changed, 150 insertions, 10 deletions

diff --git a/lib/private/Collaboration/Reference/FileReferenceProvider.php b/lib/private/Collaboration/Reference/FileReferenceProvider.php
index b7c9bc9cd56..9a4bd65249f 100644
--- a/lib/private/Collaboration/Reference/FileReferenceProvider.php
+++ b/lib/private/Collaboration/Reference/FileReferenceProvider.php
@@ -100,7 +100,7 @@ class FileReferenceProvider implements IReferenceProvider {
 		]);
 	}
 
-	public function isGloballyCachable(): bool {
+	public function isGloballyCacheable(): bool {
 		return false;
 	}
 
diff --git a/lib/private/Collaboration/Reference/LinkReferenceProvider.php b/lib/private/Collaboration/Reference/LinkReferenceProvider.php
index 51c26008b83..83bd5f954e6 100644
--- a/lib/private/Collaboration/Reference/LinkReferenceProvider.php
+++ b/lib/private/Collaboration/Reference/LinkReferenceProvider.php
@@ -124,7 +124,7 @@ class LinkReferenceProvider implements IReferenceProvider {
 		}
 	}
 
-	public function isGloballyCachable(): bool {
+	public function isGloballyCacheable(): bool {
 		return true;
 	}
 
diff --git a/lib/private/Collaboration/Reference/Reference.php b/lib/private/Collaboration/Reference/Reference.php
index 08b3847e46e..69ce7fc9597 100644
--- a/lib/private/Collaboration/Reference/Reference.php
+++ b/lib/private/Collaboration/Reference/Reference.php
@@ -25,7 +25,9 @@ declare(strict_types=1);
 
 namespace OC\Collaboration\Reference;
 
-class Reference implements \OCP\Collaboration\Reference\IReference, \JsonSerializable {
+use OCP\Collaboration\Reference\IReference;
+
+class Reference implements IReference {
 	private string $reference;
 
 	private bool $accessible = true;
@@ -120,7 +122,7 @@ class Reference implements \OCP\Collaboration\Reference\IReference, \JsonSeriali
 		];
 	}
 
-	public static function toCache(Reference $reference): array {
+	public static function toCache(IReference $reference): array {
 		return [
 			'id' => $reference->getId(),
 			'title' => $reference->getTitle(),
@@ -134,7 +136,7 @@ class Reference implements \OCP\Collaboration\Reference\IReference, \JsonSeriali
 		];
 	}
 
-	public static function fromCache(array $cache): Reference {
+	public static function fromCache(array $cache): IReference {
 		$reference = new Reference($cache['id']);
 		$reference->setTitle($cache['title']);
 		$reference->setDescription($cache['description']);
diff --git a/lib/private/Collaboration/Reference/ReferenceManager.php b/lib/private/Collaboration/Reference/ReferenceManager.php
index 0d156cd8c71..20a5d2eb5b7 100644
--- a/lib/private/Collaboration/Reference/ReferenceManager.php
+++ b/lib/private/Collaboration/Reference/ReferenceManager.php
@@ -100,7 +100,7 @@ class ReferenceManager implements IReferenceManager {
 
 	private function getCacheKey(IReferenceProvider $provider, string $referenceId): string {
 		return md5($referenceId) . (
-			$provider->isGloballyCachable()
+			$provider->isGloballyCacheable()
 				? ''
 				: '-' . md5($provider->getCacheKey($referenceId))
 		);
diff --git a/lib/public/Collaboration/Reference/IReference.php b/lib/public/Collaboration/Reference/IReference.php
index 1f4bf04c796..2a7213983cf 100644
--- a/lib/public/Collaboration/Reference/IReference.php
+++ b/lib/public/Collaboration/Reference/IReference.php
@@ -22,10 +22,100 @@
 
 namespace OCP\Collaboration\Reference;
 
-use OC\Collaboration\Reference\Reference;
+use JsonSerializable;
 
-interface IReference {
+/**
+ * @since 25.0.0
+ */
+interface IReference extends JsonSerializable {
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function getId(): string;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function setAccessible(bool $accessible): void;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function setTitle(string $title): void;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function getTitle(): string;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function setDescription(?string $description): void;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function getDescription(): ?string;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function setImageUrl(?string $imageUrl): void;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function getImageUrl(): ?string;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function setImageContentType(?string $contentType): void;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function getImageContentType(): ?string;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function setUrl(?string $url): void;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function getUrl(): ?string;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function setRichObject(string $type, array $richObject): void;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public function getRichObjectType(): string;
+
+	/**
+	 * @since 25.0.0
+	 */
 	public function getRichObject(): array;
 
-	public static function toCache(Reference $reference): array;
+	/**
+	 * @since 25.0.0
+	 */
+	public function getOpenGraphObject(): array;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public static function toCache(IReference $reference): array;
+
+	/**
+	 * @since 25.0.0
+	 */
+	public static function fromCache(array $cache): IReference;
 }
diff --git a/lib/public/Collaboration/Reference/IReferenceManager.php b/lib/public/Collaboration/Reference/IReferenceManager.php
index baf75d74838..dda0d030785 100644
--- a/lib/public/Collaboration/Reference/IReferenceManager.php
+++ b/lib/public/Collaboration/Reference/IReferenceManager.php
@@ -22,10 +22,30 @@
 
 namespace OCP\Collaboration\Reference;
 
+/**
+ * @since 25.0.0
+ */
 interface IReferenceManager {
+	/**
+	 * Return all reference identifiers within a string as an array
+	 *
+	 * @since 25.0.0
+	 */
 	public function extractReferences(string $text): array;
 
+	/**
+	 * Resolve a given reference id to its metadata with all available providers
+	 *
+	 * This method has a fallback to always provide the open graph metadata,
+	 * but may still return null in case this is disabled or the fetching fails
+	 * @since 25.0.0
+	 */
 	public function resolveReference(string $reference): ?IReference;
 
+	/**
+	 * Register a new reference provider
+	 *
+	 * @since 25.0.0
+	 */
 	public function registerReferenceProvider(IReferenceProvider $provider): void;
 }
diff --git a/lib/public/Collaboration/Reference/IReferenceProvider.php b/lib/public/Collaboration/Reference/IReferenceProvider.php
index ff0bfc8ed47..b7b2f187a65 100644
--- a/lib/public/Collaboration/Reference/IReferenceProvider.php
+++ b/lib/public/Collaboration/Reference/IReferenceProvider.php
@@ -22,9 +22,37 @@
 
 namespace OCP\Collaboration\Reference;
 
+/**
+ * @since 25.0.0
+ */
 interface IReferenceProvider {
+	/**
+	 * Validate that a given reference identifier matches the current provider
+	 *
+	 * @since 25.0.0
+	 */
 	public function matchReference(string $referenceText): bool;
+
+	/**
+	 * Return a reference with its metadata for a given reference identifier
+	 *
+	 * @since 25.0.0
+	 */
 	public function resolveReference(string $referenceText): ?IReference;
-	public function isGloballyCachable(): bool;
+
+	/**
+	 * Return true if the reference metadata can be globally cached
+	 *
+	 * @since 25.0.0
+	 */
+	public function isGloballyCacheable(): bool;
+
+	/**
+	 * Return a custom cache key to be used for caching the metadata
+	 * This could be for example the current user id if the reference
+	 * access permissions are different for each user
+	 *
+	 * @since 25.0.0
+	 */
 	public function getCacheKey(string $referenceId): string;
 }