📝 Add docstrings to fix-deployment-status

Docstrings generation was requested by @Meldiron.

* https://github.com/appwrite/appwrite/pull/9580#issuecomment-2754220710

The following files were modified:

* `app/controllers/general.php`
* `src/Appwrite/Auth/Key.php`
* `src/Appwrite/Platform/Modules/Functions/Workers/Builds.php`
* `src/Appwrite/Transformation/Adapter/Preview.php`

app/controllers/general.php

@@ -56,6 +56,25 @@ Config::setParam('domainVerification', false);
 Config::setParam('cookieDomain', 'localhost');
 Config::setParam('cookieSamesite', Response::COOKIE_SAMESITE_NONE);
 
+/**
+ * Routes an incoming HTTP request to the appropriate Appwrite resource.
+ *
+ * This function inspects the request hostname and domain rules to determine if the request should be processed as a
+ * deployment (function or site execution), API call, or redirect. It handles ACME challenges, enforces HTTPS where required,
+ * validates preview authorization (unless bypassed via the provided API key), and prepares execution parameters for deployments.
+ * It also updates metrics and logs execution details before sending the response.
+ *
+ * Returns true if the request was processed (e.g. execution triggered, redirect issued) and a response was sent, or false if
+ * the default API routing should continue.
+ *
+ * @param string $previewHostname Overrides the detected hostname for preview scenarios.
+ * @param Key|null $apiKey Optional API key that may bypass standard deployment status checks and preview authorization.
+ *
+ * @return bool True if the request was fully handled; false otherwise.
+ *
+ * @throws AppwriteException If the request violates domain restrictions, router protection, service availability,
+ *                           deployment status, authorization, or if the runtime is unsupported.
+ */
 function router(App $utopia, Database $dbForPlatform, callable $getProjectDB, SwooleRequest $swooleRequest, Request $request, Response $response, Event $queueForEvents, StatsUsage $queueForStatsUsage, Func $queueForFunctions, Reader $geodb, callable $isResourceBlocked, string $previewHostname, ?Key $apiKey)
 {
     $utopia->getRoute()?->label('error', __DIR__ . '/../views/general/error.phtml');

src/Appwrite/Auth/Key.php

@@ -12,6 +12,22 @@ use Utopia\System\System;
 
 class Key
 {
+    /**
+     * Constructs a new Key instance with the specified configuration.
+     *
+     * @param string $projectId The ID of the project associated with the key.
+     * @param string $type The type of the key (e.g., standard or dynamic).
+     * @param string $role The role associated with the key.
+     * @param array $scopes An array of scopes defining the key's permissions.
+     * @param string $name The name assigned to the key.
+     * @param bool $expired Indicates whether the key is expired. Defaults to false.
+     * @param array $disabledMetrics A list of metrics disabled for this key.
+     * @param bool $hostnameOverride Indicates if hostname override is enabled.
+     * @param bool $bannerDisabled Indicates if the banner display is disabled.
+     * @param bool $projectCheckDisabled Indicates whether project checks are disabled.
+     * @param bool $previewAuthDisabled Indicates whether preview authentication is disabled.
+     * @param bool $deploymentStatusIgnored Indicates if the deployment status should be ignored. Defaults to false.
+     */
     public function __construct(
         protected string $projectId,
         protected string $type,
@@ -75,29 +91,53 @@ class Key
         return $this->bannerDisabled;
     }
 
+    /**
+     * Returns whether preview authentication is disabled.
+     *
+     * @return bool True if preview authentication is disabled, false otherwise.
+     */
     public function isPreviewAuthDisabled(): bool
     {
         return $this->previewAuthDisabled;
     }
 
+    /**
+     * Determines if the API key's deployment status is ignored.
+     *
+     * @return bool True if the deployment status is ignored; otherwise, false.
+     */
     public function isDeploymentStatusIgnored(): bool
     {
         return $this->deploymentStatusIgnored;
     }
 
+    /**
+     * Returns whether project checks are disabled.
+     *
+     * This method indicates if project-based validations are bypassed.
+     *
+     * @return bool True if project checks are disabled; false otherwise.
+     */
     public function isProjectCheckDisabled(): bool
     {
         return $this->projectCheckDisabled;
     }
 
     /**
-     * Decode the given secret key into a Key object, containing the project ID, type, role, scopes, and name.
-     * Can be a stored API key or a dynamic key (JWT).
+     * Decodes a secret API key into a Key object.
      *
-     * @param Document $project
-     * @param string $key
-     * @return Key
-     * @throws Exception
+     * This method processes both dynamic (JWT) keys and standard API keys. For dynamic keys, it decodes the JWT payload
+     * using a secure environment key and extracts properties such as the key name, project ID, scopes, disabled metrics,
+     * hostname override, banner, project check, preview authentication, and deployment status. If decoding fails or if the
+     * project ID in the token does not match the provided project (when project checks are enabled), a guest key is returned.
+     *
+     * For standard keys, the method retrieves the key document from the project and checks for expiration, returning a guest
+     * key if the key is not found or has expired.
+     *
+     * @param Document $project The project document containing API key definitions.
+     * @param string   $key     The secret API key, either in standard format or as a dynamic JWT.
+     *
+     * @return Key A new Key instance reflecting the decoded API key or a guest key if validation fails.
      */
     public static function decode(
         Document $project,

src/Appwrite/Platform/Modules/Functions/Workers/Builds.php

@@ -45,6 +45,11 @@ use function Swoole\Coroutine\batch;
 
 class Builds extends Action
 {
+    /**
+     * Retrieves the identifier for the build action.
+     *
+     * @return string The action name "builds".
+     */
     public static function getName(): string
     {
         return 'builds';
@@ -156,26 +161,20 @@ class Builds extends Action
     }
 
     /**
-     * @param Device $deviceForFunctions
-     * @param Device $deviceForSites
-     * @param Device $deviceForFiles
-     * @param Webhook $queueForWebhooks
-     * @param Func $queueForFunctions
-     * @param Realtime $queueForRealtime
-     * @param Event $queueForEvents
-     * @param StatsUsage $queueForStatsUsage
-     * @param Database $dbForPlatform
-     * @param Database $dbForProject
-     * @param GitHub $github
-     * @param Document $project
-     * @param Document $resource
-     * @param Document $deployment
-     * @param Document $template
-     * @param Log $log
-     * @return void
-     * @throws \Utopia\Database\Exception
+     * Orchestrates the entire build deployment process for a function or site resource.
      *
-     * @throws Exception
+     * This method validates and retrieves the necessary resource and deployment documents, ensuring the resource is not blocked,
+     * and sets up real-time update channels and logging contexts. It supports two deployment flows:
+     * - A non-VCS flow that builds the resource using a template repository.
+     * - A VCS-based flow that clones the source repository (and merges templates if provided), executes build commands,
+     *   and updates source commit details.
+     *
+     * The method concurrently streams build logs from a runtime executor, verifies build size limits, and handles post-build
+     * operations such as screenshot generation for site deployments, updating deployment statuses, triggering webhooks,
+     * function events, and usage metrics, and integrating with GitHub for commit status updates.
+     *
+     * @throws \Exception If validations fail, documents are missing, cloning or build operations encounter errors,
+     *                    or deployment constraints are violated.
      */
     protected function buildDeployment(
         Device $deviceForFunctions,

src/Appwrite/Transformation/Adapter/Preview.php

@@ -27,6 +27,13 @@ class Preview extends Adapter
         return false;
     }
 
+    /**
+     * Appends a styled preview banner to the output.
+     *
+     * This method merges the existing input HTML with a preview banner, which 
+     * includes CSS for both light and dark themes and JavaScript to hide the banner 
+     * on click.
+     */
     public function transform(): void
     {
         $this->output = $this->input;