Improve TenancyUrlGenerator docblocks

src/Overrides/TenancyUrlGenerator.php

@@ -14,18 +14,33 @@ use Stancl\Tenancy\Resolvers\PathTenantResolver;
  * This class is used in place of the default UrlGenerator when UrlGeneratorBootstrapper is enabled.
  *
  * TenancyUrlGenerator does two extra things:
- * 1. Autofill the {tenant} parameter in the tenant context with the current tenant if $passTenantParameterToRoutes is enabled (enabled by default)
- * 2. Prepend the route name with `tenant.` (or the configured prefix) if $prefixRouteNames is enabled (disabled by default)
  *
- * Both of these can be skipped by passing the $bypassParameter (`['central' => true]` by default)
+ * - Autofills the tenant parameter in the tenant context with the current tenant if $passTenantParameterToRoutes is enabled.
+ * With path identification, this is done by URL::defaults() when UrlGeneratorBootstrapper::$addTenantParameterToDefaults is true (which is the default).
+ * Enabling $passTenantParameterToRoutes is preferable with query string identification.
+ *
+ * - Prepends the route name passed to route() and URL::temporarySignedRoute()
+ * with `tenant.` (or the configured prefix) if $prefixRouteNames is enabled (disabled by default).
+ * Primarily intended to be used with path identification.
+ *
+ * This behavior can be bypassed by passing the $bypassParameter to the mentioned methods (`['central' => true]` by default).
  */
 class TenancyUrlGenerator extends UrlGenerator
 {
     /**
      * Parameter which bypasses the behavior modification of route() and temporarySignedRoute().
      *
-     * E.g. route('tenant') => app.test/{tenant}/tenant (or app.test/tenant?tenant=tenantKey if the route doesn't accept the tenant parameter)
+     * For example, in tenant context:
-     * route('tenant', [$bypassParameter => true]) => app.test/tenant.
+     * Route::get('/', ...)->name('home');
+     * Route::get('/tenant', ...)->middleware(InitializeTenancyByRequestData::class)->name('tenant.home');
+     * - route('home') => app.test/tenant?tenant=tenantKey
+     * - route('home', [$bypassParameter => true]) => app.test/
+     * - route('tenant.home', [$bypassParameter => true]) => app.test/tenant  -- query string identification (no query string passed)
+     *
+     * With path identification, the tenant parameter is passed automatically by URL::defaults(), so in that case,
+     * this only affects the automatic route name prefixing.
+     *
+     * @see UrlGeneratorBootstrapper
      */
     public static string $bypassParameter = 'central';
 
@@ -41,8 +56,12 @@ class TenancyUrlGenerator extends UrlGenerator
     /**
      * Determine if the tenant parameter should get passed
      * to the links generated by `route()` or `temporarySignedRoute()` whenever available.
+     * This is primarily intended to be used with query string identification.
      *
-     * With path identification, you can keep this disabled since the parameter is passed automatically by URL::defaults() in the UrlGeneratorBootstrapper
+     * With path identification, the tenant parameter is passed by URL::defaults()
+     * when UrlGeneratorBootstrapper::$addTenantParameterToDefaults is true (which is the default).
+     *
+     * @see UrlGeneratorBootstrapper
      */
     public static bool $passTenantParameterToRoutes = false;
 
@@ -123,7 +142,7 @@ class TenancyUrlGenerator extends UrlGenerator
     }
 
     /**
-     * If `tenant()` isn't null, add tenant paramter to the passed parameters.
+     * If `tenant()` isn't null, add tenant parameter to the passed parameters.
      */
     protected function addTenantParameter(array $parameters): array
     {