Add full public interfaces

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

3 files changed, 142 insertions, 4 deletions

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;
 }