core: Document text processing API

Signed-off-by: jld3103 <jld3103yt@gmail.com>

Author: provokateurin

core/Controller/TextProcessingApiController.php

@@ -27,6 +27,7 @@
 namespace OC\Core\Controller;
 
 use InvalidArgumentException;
+use OCA\Core\ResponseDefinitions;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\Common\Exception\NotFoundException;
@@ -41,6 +42,9 @@
 use Psr\Container\NotFoundExceptionInterface;
 use Psr\Log\LoggerInterface;
 
+/**
+ * @psalm-import-type CoreTextProcessingTask from ResponseDefinitions
+ */
 class TextProcessingApiController extends \OCP\AppFramework\OCSController {
 	public function __construct(
 		string           $appName,
@@ -58,10 +62,13 @@ public function __construct(
 	 * This endpoint returns all available LanguageModel task types
 	 *
 	 * @PublicPage
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{types: array{id: string, name: string, description: string}[]}, array{}>
 	 */
 	public function taskTypes(): DataResponse {
 		$typeClasses = $this->languageModelManager->getAvailableTaskTypes();
 		$types = [];
+		/** @var string $typeClass */
 		foreach ($typeClasses as $typeClass) {
 			try {
 				/** @var ITaskType $object */
@@ -88,6 +95,17 @@ public function taskTypes(): DataResponse {
 	 * @PublicPage
 	 * @UserRateThrottle(limit=20, period=120)
 	 * @AnonRateThrottle(limit=5, period=120)
+	 *
+	 * @param string $input Input text
+	 * @param string $type Type of the task
+	 * @param string $appId ID of the app that will execute the task
+	 * @param string $identifier An arbitrary identifier for the task
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{task: CoreTextProcessingTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_PRECONDITION_FAILED, array{message: string}, array{}>
+	 *
+	 * 200: Task scheduled successfully
+	 * 400: Scheduling task is not possible
+	 * 412: Scheduling task is not possible
 	 */
 	public function schedule(string $input, string $type, string $appId, string $identifier = ''): DataResponse {
 		try {
@@ -114,6 +132,11 @@ public function schedule(string $input, string $type, string $appId, string $ide
 	 *
 	 * @PublicPage
 	 * @param int $id The id of the task
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{task: CoreTextProcessingTask}, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
+	 *
+	 * 200: Task returned
+	 * 404: Task not found
 	 */
 	public function getTask(int $id): DataResponse {
 		try {

core/ResponseDefinitions.php

@@ -126,6 +126,17 @@
  *     subline: string,
  *     shareWithDisplayNameUnique: string,
  * }
+ *
+ * @psalm-type CoreTextProcessingTask = array{
+ *     id: ?int,
+ *     type: string,
+ *     status: 0|1|2|3|4,
+ *     userId: ?string,
+ *     appId: string,
+ *     input: string,
+ *     output: ?string,
+ *     identifier: string,
+ * }
  */
 class ResponseDefinitions {
 }