From 1a693d8e36b02d98cac6a9a79b6580efad486408 Mon Sep 17 00:00:00 2001
From: lukinovec <lukinovec@gmail.com>
Date: Thu, 20 Aug 2026 15:32:12 +0200
Subject: [PATCH] Improve comments

Correct misleading ones, add ones that were missing (e.g. the TenantAssetController's docblock, the FSBootstrapper dependency should be mentioned there)
---
 .../FilesystemTenancyBootstrapper.php         |  4 ++--
 src/Controllers/TenantAssetController.php     | 20 +++++++++++++++----
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/src/Bootstrappers/FilesystemTenancyBootstrapper.php b/src/Bootstrappers/FilesystemTenancyBootstrapper.php
index 7235674b..05d480e4 100644
--- a/src/Bootstrappers/FilesystemTenancyBootstrapper.php
+++ b/src/Bootstrappers/FilesystemTenancyBootstrapper.php
@@ -331,8 +331,8 @@ class FilesystemTenancyBootstrapper implements TenancyBootstrapper
     /**
      * Get the storage path of the passed tenant (independent of the current context).
      *
-     * The returned path doesn't depend on suffix_storage_path -- that config option
-     * only controls whether storage_path() uses it.
+     * Note that the returned path doesn't depend on suffix_storage_path.
+     * That config option only affects the storage_path() helper.
      */
     public static function getBoundTenantStoragePath(Tenant $tenant): string
     {
diff --git a/src/Controllers/TenantAssetController.php b/src/Controllers/TenantAssetController.php
index 48da0b01..7926c1ce 100644
--- a/src/Controllers/TenantAssetController.php
+++ b/src/Controllers/TenantAssetController.php
@@ -13,6 +13,13 @@ use Stancl\Tenancy\Bootstrappers\FilesystemTenancyBootstrapper;
 use Symfony\Component\HttpFoundation\BinaryFileResponse;
 use Throwable;
 
+/**
+ * Requires FilesystemTenancyBootstrapper to be enabled, since the assets are served from
+ * the tenant's storage directory (or from the root of $publicDisk), and neither is
+ * tenant-specific unless the bootstrapper scopes it.
+ *
+ * @see FilesystemTenancyBootstrapper
+ */
 class TenantAssetController implements HasMiddleware
 {
     /**
@@ -33,6 +40,10 @@ class TenantAssetController implements HasMiddleware
      * Disk the assets are served from.
      *
      * When null, the assets are served from app/public inside the tenant's storage directory.
+     *
+     * The disk has to be local and have a root configured, since the assets are read from the filesystem.
+     * It should also be listed in tenancy.filesystem.disks. FilesystemTenancyBootstrapper only scopes
+     * the roots of disks listed there, so otherwise every tenant is served the same central directory.
      */
     public static string|null $publicDisk = null;
 
@@ -66,11 +77,12 @@ class TenantAssetController implements HasMiddleware
     }
 
     /**
-     * Directory the assets are served from -- the root of the $publicDisk,
-     * or app/public inside the tenant's storage directory when no disk is configured.
+     * Directory the assets are served from -- the root of the $publicDisk, or app/public
+     * inside the tenant's storage directory when no disk is configured. With no current
+     * tenant (e.g. on a universal route), the central storage directory is used.
      *
-     * The storage directory is resolved using the FilesystemTenancyBootstrapper (rather than
-     * storage_path(), so that it's tenant-scoped regardless of the suffix_storage_path config).
+     * The tenant's storage directory is resolved using the FilesystemTenancyBootstrapper (rather
+     * than storage_path(), so that it's tenant-scoped regardless of the suffix_storage_path config).
      */
     protected function assetRoot(): string
     {