improve comments

assets/config.php

@@ -321,11 +321,12 @@ return [
 
     /**
      * Filesystem tenancy config. Used by FilesystemTenancyBootstrapper.
-     * https://v4.tenancyforlaravel.com/bootstrappers/filesystem.
+     * https://v4.tenancyforlaravel.com/bootstrappers/filesystem
      */
     'filesystem' => [
         /**
-         * Each disk listed in the 'disks' array will be suffixed by the suffix_base, followed by the tenant_id.
+         * Each disk listed in the 'disks' array will have its root
+         * suffixed by the suffix_base, followed by the tenant_id.
          */
         'suffix_base' => 'tenant',
         'disks' => [
@@ -337,11 +338,13 @@ return [
         /**
          * Use this for local disks.
          *
-         * The override can use these placeholders:
-         * - %storage_path% -- the tenant's storage directory. Note that this is resolved
-         *   by the bootstrapper, so it doesn't depend on the 'suffix_storage_path' config below.
+         * Customizes how the disk's root is scoped, instead of the default behavior
+         * which simply appends the tenant suffix to the original root.
+         *
+         * The overrides can reference the following placeholders:
+         * - %storage_path% -- the tenant's storage directory
          * - %original_storage_path% -- the central storage directory.
-         * - %tenant% -- the tenant's key.
+         * - %tenant% -- the tenant key.
          *
          * See https://v4.tenancyforlaravel.com/bootstrappers/filesystem
          */
@@ -364,7 +367,7 @@ return [
          */
         'url_override' => [
             // Note that the local disk you add must exist in the tenancy.filesystem.disks config,
-            // and it must have a non-falsy root (i.e., not null or empty string).
+            // and it must have a non-falsy root (not null nor an empty string).
             'public' => 'public-%tenant%',
         ],
 
@@ -385,14 +388,7 @@ return [
         /**
          * Should storage_path() be suffixed.
          *
-         * Note: This only affects the storage_path() helper. Disks listed in the 'disks' config
-         * above, and cache and sessions if 'scope_cache' and 'scope_sessions' are enabled, are
-         * scoped to the tenant's storage directory either way. With this disabled, files
-         * accessed using storage_path() are shared by all tenants.
-         *
-         * For the vast majority of applications, this feature should be enabled. But in some
-         * edge cases, it can cause issues (like using Passport with Vapor - see #196), so
-         * you may want to disable this if you are experiencing these edge case issues.
+         * Only affects the storage_path() helper, other features use the tenant storage directory regardless.
          */
         'suffix_storage_path' => true,
 

src/Controllers/TenantAssetController.php

@@ -17,15 +17,11 @@ use Throwable;
 
 /**
  * Serves files from app/public inside the tenant's storage directory, or from the root
- * of the $publicDisk when one is configured.
+ * of the $publicDisk when the property is set.
  *
- * Requires FilesystemTenancyBootstrapper to be enabled since it points the public disk's
- * root at the tenant's storage directory. Without it, the disk keeps writing to the central
- * storage/app/public, so the tenant's directory is never populated and requests 404
- * (the path itself is tenant-specific either way, via getBoundTenantStoragePath()).
- *
- * With a $publicDisk configured, the assets come from that disk's root instead. The
- * bootstrapper is needed to make that root tenant-specific (see $publicDisk).
+ * Requires FilesystemTenancyBootstrapper to be enabled, so that writes to the default
+ * public disk end up in the app/public within the *tenant's* storage, or so that the
+ * public disk set in the static property is similarly scoped.
  *
  * @see FilesystemTenancyBootstrapper
  */
@@ -55,8 +51,8 @@ class TenantAssetController implements HasMiddleware
      *
      * It should also be listed in tenancy.filesystem.disks -- for scoped disks, it's the parent
      * disk that has to be listed there (since a scoped disk inherits the parent's root).
-     * FilesystemTenancyBootstrapper only scopes the roots of disks listed there, so otherwise
-     * every tenant is served the same (central) directory.
+     * FilesystemTenancyBootstrapper only scopes the roots of disks listed there, so
+     * without that every tenant would be served the same (central) directory.
      */
     public static string|null $publicDisk = null;
 
@@ -142,7 +138,7 @@ class TenantAssetController implements HasMiddleware
 
         // User is attempting to access a file outside the $allowedRoot folder.
         // The trailing separator is needed so that sibling directories that
-        // start with the same name (e.g. app/public-private) don't pass.
+        // start with the same name (e.g. app/public-private) aren't accepted.
         $this->abortIf(! str($attemptedPath)->startsWith(rtrim($allowedRoot, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR), 'Accessing a file outside the storage root');
     }
 

src/Jobs/DeleteTenantStorage.php

@@ -16,16 +16,11 @@ use Stancl\Tenancy\Contracts\Tenant;
 /**
  * Delete the tenant's storage directory.
  *
- * The directory is the one FilesystemTenancyBootstrapper scopes the tenant's disks, cache
- * and sessions to. The path is derived the same way the bootstrapper derives it, so the
- * bootstrapper doesn't *have* to be enabled (though if it isn't, nothing was written there and
- * there's nothing to delete).
- *
- * Files outside that directory (e.g. disks with an %original_storage_path%-based
- * root_override) are not deleted.
- *
- * Note that this job is not affected by the tenancy.filesystem.suffix_storage_path config
- * since it doesn't use the storage_path() helper.
+ * The directory is used by the FilesystemTenancyBootstrapper for:
+ * - scoped storage_path() when suffix_storage_path is enabled
+ * - scoped cache when enabled
+ * - scoped sessions when enabled
+ * - scoped disks when enabled
  *
  * @see FilesystemTenancyBootstrapper
  */