MediaHandler.php: update documentation

inc/Service/Media/MediaHandler.php

@@ -6,7 +6,7 @@ use Vichan\Data\ThumbGenerationResult;
 
 interface MediaHandler {
 	/**
-	 * PHP file upload,
+	 * PHP file upload. The handler may move or otherwise invalidate this file.
 	 */
 	public const FILE_KIND_UPLOADED = 0;
 	/**
@@ -14,19 +14,40 @@ interface MediaHandler {
 	 */
 	public const FILE_KIND_TEMPORARY = 1;
 	/**
-	 * Static vichan file.
+	 * Static file from somewhere in the filesystem.
 	 */
 	public const FILE_KIND_STATIC = 2;
 	/**
-	 * Live file in use by vichan in some post.
+	 * Live file currently in use by vichan in some post somewhere.
 	 */
 	public const FILE_KIND_INSTALLED = 3;
 
 
+	/**
+	 * Check if this handler implementation supports the files of the given mime type.
+	 *
+	 * @param string $mime Mime type string.
+	 * @return bool Returns true if the handler supports the file type.
+	 */
 	public function supportsMime(string $mime): bool;
 
+	/**
+	 * Opens a SINGLE USE handle over a file. After using the handle with any method of this class, the handle MUST be
+	 * closed with {@link closeHandle}
+	 *
+	 * @param string $file_path Path to the file.
+	 * @param string $file_mime The mime type of the file. MUST be of a value for which {@link supportsMime} returns true.
+	 * @param int $file_kind One of the FILE_KIND_* constants.
+	 * @return mixed An opaque handle.
+	 * @throws \RuntimeException On error.
+	 */
 	public function openHandle(string $file_path, string $file_mime, int $file_kind): mixed;
 
+	/**
+	 * Closes the handle.
+	 * @param mixed $handle Handle to close, MUST NOT have already been closed.
+	 * @return void
+	 */
 	public function closeHandle(mixed $handle);
 
 	public function installMediaAndGenerateThumb(
@@ -43,13 +64,14 @@ interface MediaHandler {
 	/**
 	 * Generates a thumbnail from the given file.
 	 *
-	 * @param string $source_file_path
+	 * @param mixed $handle An opaque handle obtained from {@link openHandle}.
-	 * @param string $source_file_mime
+	 * @param string $preferred_out_file_dir
-	 * @param string $preferred_out_file_path
+	 * @param string $preferred_out_file_name
 	 * @param string $preferred_out_mime
 	 * @param int $max_width
 	 * @param int $max_height
 	 * @return ThumbGenerationResult
+	 * @throws \RuntimeException On error.
 	 */
 	public function generateThumb(
 		mixed $handle,