Merge pull request #61632 from nextcloud/jtr/docs-IPreview-and-IProviderV2

docs(preview): improve IPreview and IProviderV2 interface docs

Author: CarlSchwan

lib/public/IPreview.php

@@ -17,25 +17,39 @@
 use OCP\Preview\IProviderV2;
 
 /**
- * This class provides functions to render and show thumbnails and previews of files
+ * Public interface for discovering preview providers and generating file previews.
+ *
+ * ProviderClosure lazily resolves a preview provider and may return false if it
+ * cannot be loaded.
+ *
  * @since 6.0.0
  * @psalm-type ProviderClosure = Closure():(IProviderV2|false)
  */
 #[Consumable(since: '6.0.0')]
 interface IPreview {
 	/**
+	 * Preview scaling mode that fills the requested dimensions.
+	 *
 	 * @since 11.0.0
 	 */
 	public const MODE_FILL = 'fill';
 
 	/**
+	 * Preview scaling mode that covers the requested dimensions.
+	 *
 	 * @since 11.0.0
 	 */
 	public const MODE_COVER = 'cover';
 
 	/**
-	 * Get all providers
-	 * @return array<string, list<ProviderClosure>>
+	 * Returns the registered preview providers grouped by supported mime-type regex.
+	 *
+	 * Each value is a list of closures that create preview providers when invoked,
+	 * not a list of already instantiated provider objects.
+	 *
+	 * The provider list is built on demand and is empty when previews are disabled.
+	 *
+	 * @return array<string, list<ProviderClosure>> Map of mime-type regex to provider-creating closures
 	 * @since 8.1.0
 	 */
 	public function getProviders(): array;
@@ -64,17 +78,25 @@ public function hasProviders(): bool;
 	public function getPreview(File $file, int $width = -1, int $height = -1, bool $crop = false, string $mode = IPreview::MODE_FILL, ?string $mimeType = null, bool $cacheResult = true): ISimpleFile;
 
 	/**
-	 * Returns true if the passed mime type is supported
-	 * @param string $mimeType A glob
+	 * Returns whether any registered preview provider supports the given mime type.
+	 *
+	 * This checks the mime type against the providers' registered mime-type regexes.
+	 * It does not guarantee that preview generation will succeed for a specific file.
+	 *
+	 * @param string $mimeType Mime type string to test, for example "image/png"
 	 * @since 6.0.0
 	 */
 	public function isMimeSupported(string $mimeType = '*'): bool;
 
 	/**
-	 * Check if a preview can be generated for a file
+	 * Returns whether a preview can currently be generated for the given file.
+	 *
+	 * This checks whether the effective mime type is supported, whether previews
+	 * are allowed on the file's mount, and whether at least one matching provider is
+	 * available for the file in the current environment.
 	 *
 	 * @param FileInfo $file
-	 * @param string|null $mimeType To force a given mimetype for the file
+	 * @param string|null $mimeType Optional mime type override to use instead of $file->getMimeType()
 	 * @since 8.0.0
 	 * @since 32.0.0 - isAvailable($mimeType) added the $mimeType argument to the signature
 	 */

lib/public/Preview/IProviderV2.php

@@ -13,31 +13,35 @@
 use OCP\IImage;
 
 /**
+ * Public interface for preview providers.
+ *
+ * A preview provider generates a thumbnail image for supported files. That image
+ * may be stored and reused by the preview system.
+ *
  * @since 17.0.0
  */
 interface IProviderV2 {
 	/**
-	 * @return string Regex with the mimetypes that are supported by this provider
+	 * Returns a regex matching the MIME types supported by this provider.
+	 *
 	 * @since 17.0.0
 	 */
 	public function getMimeType(): string;
 
 	/**
-	 * Check if a preview can be generated for $path
+	 * Returns whether this provider can currently generate a thumbnail for the given file.
 	 *
-	 * @param FileInfo $file
-	 * @return bool
 	 * @since 17.0.0
 	 */
 	public function isAvailable(FileInfo $file): bool;
 
 	/**
-	 * get thumbnail for file at path $path
+	 * Generates a thumbnail image for the given file.
 	 *
 	 * @param File $file
-	 * @param int $maxX The maximum X size of the thumbnail. It can be smaller depending on the shape of the image
-	 * @param int $maxY The maximum Y size of the thumbnail. It can be smaller depending on the shape of the image
-	 * @return null|\OCP\IImage null if no preview was generated
+	 * @param int $maxX Maximum thumbnail width; the returned image may be smaller depending on its aspect ratio
+	 * @param int $maxY Maximum thumbnail height; the returned image may be smaller depending on its aspect ratio
+	 * @return IImage|null Null if no thumbnail could be generated
 	 * @since 17.0.0
 	 */
 	public function getThumbnail(File $file, int $maxX, int $maxY): ?IImage;