doc comment improvements

Author: eli-darkly

src/LaunchDarkly/LDClient.php

@@ -178,9 +178,9 @@ private function getFeatureRequester(string $sdkKey, array $options): FeatureReq
      * does not match any existing flag), `$defaultValue` is returned.
      *
      * @param string $key the unique key for the feature flag
-     * @param LDContext|LDUser $context the evaluation context
+     * @param LDContext|LDUser $context the evaluation context or user
      * @param mixed $defaultValue the default value of the flag
-     * @return mixed the variation for the given context, or `$defaultValue` if the flag cannot be evaluated
+     * @return mixed The variation for the given context, or `$defaultValue` if the flag cannot be evaluated
      * @see \LaunchDarkly\LDClient::variationDetail()
      */
     public function variation(string $key, LDContext|LDUser $context, mixed $defaultValue = false): mixed
@@ -197,10 +197,10 @@ public function variation(string $key, LDContext|LDUser $context, mixed $default
      * detailed event data for this flag.
      *
      * @param string $key the unique key for the feature flag
-     * @param LDContext|LDUser $context the evaluation context
+     * @param LDContext|LDUser $context the evaluation context or user
      * @param mixed $defaultValue the default value of the flag
      *
-     * @return EvaluationDetail an EvaluationDetail object that includes the feature flag value
+     * @return EvaluationDetail An EvaluationDetail object that includes the feature flag value
      * and evaluation reason
      */
     public function variationDetail(string $key, LDContext|LDUser $context, mixed $defaultValue = false): EvaluationDetail
@@ -295,14 +295,20 @@ public function isOffline(): bool
     }
 
     /**
-     * Tracks that a user performed an event.
+     * Tracks that an application-defined event occurred.
+     * 
+     * This method creates a "custom" analytics event containing the specified event name (key)
+     * and context properties. You may attach arbitrary data or a metric value to the event with the
+     * optional `data` and `metricValue` parameters.
+     *
+     * Note that event delivery is asynchronous, so the event may not actually be sent until later;
+     * see {@see \LaunchDarkly\LDClient::flush()}.
      *
      * @param string $eventName The name of the event
-     * @param LDContext|LDUser $context The evaluation context associated with the event
+     * @param LDContext|LDUser $context The evaluation context or user associated with the event
      * @param mixed $data Optional additional information to associate with the event
      * @param int|float|null $metricValue A numeric value used by the LaunchDarkly experimentation feature in
-     *   numeric custom metrics. Can be omitted if this event is used by only non-numeric metrics. This
-     *   field will also be returned as part of the custom event for Data Export.
+     *   numeric custom metrics; can be omitted if this event is used by only non-numeric metrics
      */
     public function track(string $eventName, LDContext|LDUser $context, mixed $data = null, int|float|null $metricValue = null): void
     {
@@ -315,12 +321,17 @@ public function track(string $eventName, LDContext|LDUser $context, mixed $data
     }
 
     /**
-     * Reports details about a user.
+     * Reports details about an evaluation context or user.
+     *
+     * This method simply creates an analytics event containing the context properties, to
+     * that LaunchDarkly will know about that context if it does not already.
      *
-     * This simply registers the given user properties with LaunchDarkly without evaluating a feature flag.
-     * This also happens automatically when you evaluate a flag.
+     * Evaluating a flag, by calling {@see \LaunchDarkly\LDClient::variation()} or
+     * {@see \LaunchDarkly\LDClient::variationDetail()} :func:`variation_detail()`, also sends
+     * the context information to LaunchDarkly (if events are enabled), so you only need to use
+     * identify() if you want to identify the context without evaluating a flag.
      *
-     * @param LDContext|LDUser $context The user properties
+     * @param LDContext|LDUser $context The context or user to register
      * @return void
      */
     public function identify(LDContext|LDUser $context): void
@@ -342,7 +353,7 @@ public function identify(LDContext|LDUser $context): void
      *
      * This method does not send analytics events back to LaunchDarkly.
      *
-     * @param LDContext|LDUser $context the evalation context
+     * @param LDContext|LDUser $context the evalation context or user
      * @param array $options Optional properties affecting how the state is computed:
      * - `clientSideOnly`: Set this to true to specify that only flags marked for client-side use
      * should be included; by default, all flags are included
@@ -399,8 +410,8 @@ public function allFlagsState(LDContext|LDUser $context, array $options = []): F
      *
      * See: [Secure mode](https://docs.launchdarkly.com/sdk/features/secure-mode)
      *
-     * @param LDContext|LDUser $context the evaluation context
-     * @return string the hash value
+     * @param LDContext|LDUser $context The evaluation context or user
+     * @return string The hash value
      */
     public function secureModeHash(LDContext|LDUser $context): string
     {

src/LaunchDarkly/LDContextBuilder.php

@@ -97,7 +97,7 @@ public function key(string $key): LDContextBuilder
     /**
      * Sets the context's kind attribute.
      *
-     * Every LDContext has a kind. Setting it to an empty string or null is equivalent to
+     * Every context has a kind. Setting it to an empty string or null is equivalent to
      * {@see \LaunchDarkly\LDContext::DEFAULT_KIND} ("user"). This value is case-sensitive.
      *
      * The meaning of the context kind is completely up to the application. Validation rules are