docs: add phpdoc summaries, examples, and docs links to resource classes

src/Alias.php

@@ -45,6 +45,13 @@ public function endPointPath(): string
     }
 
     /**
+     * Find out which collection an alias points to by fetching it.
+     *
+     * @example
+     * $client->aliases['my-alias']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/collection-alias.html#retrieve-an-alias
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */
@@ -54,6 +61,13 @@ public function retrieve(): array
     }
 
     /**
+     * Delete an alias.
+     *
+     * @example
+     * $client->aliases['my-alias']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/collection-alias.html#delete-an-alias
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

src/Aliases.php

@@ -47,6 +47,13 @@ public function endPointPath(string $aliasName): string
     }
 
     /**
+     * Create or update an alias mapping for a collection.
+     *
+     * @example
+     * $client->aliases->upsert('my-alias', ['collection_name' => 'products'])
+     *
+     * @see https://typesense.org/docs/latest/api/collection-alias.html#upsert-an-alias
+     *
      * @param string $name
      * @param array $mapping
      *
@@ -59,6 +66,13 @@ public function upsert(string $name, array $mapping): array
     }
 
     /**
+     * List all aliases and the collections they map to.
+     *
+     * @example
+     * $client->aliases->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/collection-alias.html#list-all-aliases
+     *
      * @return array
      * @throws TypesenseClientError|HttpClientException
      */

src/Analytics.php

@@ -17,6 +17,17 @@ public function __construct(ApiCall $apiCall)
         $this->apiCall = $apiCall;
     }
 
+    /**
+     * Access the analytics rules resource. Use as a method-style endpoint to list or create rules,
+     * or chain `[$id]` on the returned object to access a single rule.
+     *
+     * @example
+     * $client->analytics->rules()->retrieve()
+     * @example
+     * $client->analytics->rules()['rule-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     */
     public function rules()
     {
         if (!isset($this->rules)) {
@@ -25,6 +36,14 @@ public function rules()
         return $this->rules;
     }
 
+    /**
+     * Access the analytics events resource to send analytics events.
+     *
+     * @example
+     * $client->analytics->events()->create(['type' => 'click', 'name' => 'products_click', 'data' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     */
     public function events()
     {
         if (!isset($this->events)) {

src/AnalyticsEvents.php

@@ -29,8 +29,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
-     * Create an analytics event
-     * 
+     * Submit a single analytics event. The event must correspond to an existing analytics rule by name.
+     *
+     * @example
+     * $client->analytics->events()->create(['type' => 'click', 'name' => 'products_click', 'data' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @param array $params Event parameters including name, event_type, and data
      * @return array Response from the API
      * @throws TypesenseClientError|HttpClientException
@@ -41,8 +46,13 @@ public function create(array $params)
     }
 
     /**
-     * Retrieve analytics events
-     * 
+     * Retrieve the most recent events for a user and rule.
+     *
+     * @example
+     * $client->analytics->events()->retrieve(['user_id' => 'u1', 'name' => 'products_click', 'n' => 10])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @param array $params Query parameters
      * @return array Response from the API
      */

src/AnalyticsEventsV1.php

@@ -27,6 +27,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
+     * Submit a legacy v1 analytics event.
+     *
+     * @example
+     * $client->analyticsV1->events()->create(['type' => 'click', 'name' => 'products_click', 'data' => []])
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     *
      * @param array $params
      *
      * @return array

src/AnalyticsRule.php

@@ -14,8 +14,13 @@ public function __construct(string $ruleName, ApiCall $apiCall)
     }
 
     /**
-     * Retrieve a specific analytics rule
-     * 
+     * Retrieve the details of an analytics rule, given its name.
+     *
+     * @example
+     * $client->analytics->rules()['rule-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @return array Response from the API
      */
     public function retrieve()
@@ -24,8 +29,13 @@ public function retrieve()
     }
 
     /**
-     * Delete a specific analytics rule
-     * 
+     * Permanently deletes an analytics rule, given its name.
+     *
+     * @example
+     * $client->analytics->rules()['rule-1']->delete()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @return array Response from the API
      */
     public function delete()
@@ -34,8 +44,13 @@ public function delete()
     }
 
     /**
-     * Update a specific analytics rule
-     * 
+     * Upserts an analytics rule with the given name.
+     *
+     * @example
+     * $client->analytics->rules()['rule-1']->update(['type' => 'popular_queries', 'params' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @param array $params Rule parameters
      * @return array Response from the API
      */

src/AnalyticsRuleV1.php

@@ -13,11 +13,27 @@ public function __construct(string $ruleName, ApiCall $apiCall)
         $this->apiCall  = $apiCall;
     }
 
+    /**
+     * Retrieve a legacy v1 analytics rule by name.
+     *
+     * @example
+     * $client->analyticsV1->rules()['rule-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     */
     public function retrieve()
     {
         return $this->apiCall->get($this->endpointPath(), []);
     }
 
+    /**
+     * Delete a legacy v1 analytics rule by name.
+     *
+     * @example
+     * $client->analyticsV1->rules()['rule-1']->delete()
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     */
     public function delete()
     {
         return $this->apiCall->delete($this->endpointPath());

src/AnalyticsRules.php

@@ -19,8 +19,13 @@ public function __construct(ApiCall $apiCall)
     }
 
     /**
-     * Create multiple analytics rules
-     * 
+     * Create one or more analytics rules. You can send a single rule object or an array of rule objects.
+     *
+     * @example
+     * $client->analytics->rules()->create(['name' => 'products_query_hits', 'type' => 'popular_queries', 'params' => []])
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @param array $rules Array of rule objects
      * @return array Response from the API
      */
@@ -30,8 +35,13 @@ public function create(array $rules)
     }
 
     /**
-     * Retrieve all analytics rules
-     * 
+     * Retrieve all analytics rules.
+     *
+     * @example
+     * $client->analytics->rules()->retrieve()
+     *
+     * @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
+     *
      * @return array Response from the API
      */
     public function retrieve()

src/AnalyticsRulesV1.php

@@ -22,11 +22,27 @@ public function __get($ruleName)
         return $this->analyticsRules[$ruleName];
     }
 
+    /**
+     * Upsert a legacy v1 analytics rule by name.
+     *
+     * @example
+     * $client->analyticsV1->rules()->upsert('products_query_hits', ['type' => 'popular_queries', 'params' => []])
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     */
     public function upsert($ruleName, $params)
     {
         return $this->apiCall->put($this->endpoint_path($ruleName), $params);
     }
 
+    /**
+     * Retrieve all legacy v1 analytics rules.
+     *
+     * @example
+     * $client->analyticsV1->rules()->retrieve()
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     */
     public function retrieve()
     {
         return $this->apiCall->get($this->endpoint_path(), []);

src/AnalyticsV1.php

@@ -2,6 +2,9 @@
 
 namespace Typesense;
 
+/**
+ * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->analytics` (new Analytics APIs).
+ */
 class AnalyticsV1
 {
     const RESOURCE_PATH = '/analytics';
@@ -17,6 +20,19 @@ public function __construct(ApiCall $apiCall)
         $this->apiCall = $apiCall;
     }
 
+    /**
+     * Access the legacy v1 analytics rules resource. Use as a method-style endpoint to list or upsert rules,
+     * or chain `[$id]` on the returned object to access a single rule.
+     *
+     * @example
+     * $client->analyticsV1->rules()->retrieve()
+     * @example
+     * $client->analyticsV1->rules()['rule-1']->retrieve()
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     *
+     * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->analytics` (new Analytics APIs).
+     */
     public function rules()
     {
         if (!isset($this->rules)) {
@@ -25,6 +41,16 @@ public function rules()
         return $this->rules;
     }
 
+    /**
+     * Access the legacy v1 analytics events resource to send analytics events.
+     *
+     * @example
+     * $client->analyticsV1->events()->create(['type' => 'click', 'name' => 'products_click', 'data' => []])
+     *
+     * @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
+     *
+     * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `$client->analytics` (new Analytics APIs).
+     */
     public function events()
     {
         if (!isset($this->events)) {