Merge branch 'main' into dob/modelConfig

packages/sdk/browser/src/index.ts

@@ -6,7 +6,7 @@
  * In typical usage, you will call {@link initialize} once at startup time to obtain an instance of
  * {@link LDClient}, which provides access to all of the SDK's functionality.
  *
- * For more information, see the SDK reference guide.
+ * For more information, see the [SDK Reference Guide](https://docs.launchdarkly.com/sdk/client-side/javascript).
  *
  * @packageDocumentation
  */
@@ -74,11 +74,11 @@ export type {
  * Usage:
  * ```
  * import { initialize } from 'launchdarkly-js-client-sdk';
- * const client = initialize(envKey, context, options);
+ * const client = initialize(clientSideId, context, options);
  * ```
  *
  * @param clientSideId
- *   The client-side id, also known as the environment ID.
+ *   The client-side ID, also known as the environment ID.
  * @param options
  *   Optional configuration settings.
  * @return
@@ -90,10 +90,11 @@ export function initialize(clientSideId: string, options?: LDOptions): LDClient
 }
 
 /**
- * Provides a simple {@link LDLogger} implementation.
+ * Provides a basic {@link LDLogger} implementation.
  *
- * This logging implementation uses a simple format that includes only the log level
- * and the message text. By default the output is written to `console.error`.
+ * This logging implementation uses a basic format that includes only the log level
+ * and the message text. By default this uses log level 'info' and the output is
+ * written to `console.error`.
  *
  * To use the logger created by this function, put it into {@link LDOptions.logger}. If
  * you do not set {@link LDOptions.logger} to anything, the SDK uses a default logger

packages/sdk/browser/src/options.ts

@@ -24,6 +24,9 @@ export interface BrowserOptions extends Omit<LDOptionsBase, 'initialConnectionMo
    * A function which, if present, can change the URL in analytics events to something other
    * than the actual browser URL. It will be called with the current browser URL as a parameter,
    * and returns the value that should be stored in the event's `url` property.
+   *
+   * It may be useful to customize the `url` to provide specific meaning, incorporate
+   * client-side routing concerns, or redact tokens or other info.
    */
   eventUrlTransformer?: (url: string) => string;
 
@@ -39,10 +42,10 @@ export interface BrowserOptions extends Omit<LDOptionsBase, 'initialConnectionMo
   streaming?: boolean;
 
   /**
-   * Determines if the SDK responds to entering different visibility states to handle tasks such as
-   * flushing events.
+   * Determines if the SDK responds to entering different visibility states, such as foreground and background.
+   * An example is flushing buffered events when going to the background.
    *
-   * This is true by default. Generally speaking the SDK will be able to most reliably delivery
+   * This is true by default. Generally speaking the SDK will be able to most reliably deliver
    * events with this setting on.
    *
    * It may be useful to disable for environments where not all window/document objects are

packages/shared/common/src/api/context/LDContext.ts

@@ -3,6 +3,21 @@ import { LDSingleKindContext } from './LDSingleKindContext';
 import { LDUser } from './LDUser';
 
 /**
- * A LaunchDarkly context object.
+ * A LaunchDarkly context object.  LaunchDarkly contexts are objects representing users, devices, organizations, and
+ * other entities that feature flags serve different variations to according to your flag targeting rules. These data
+ * objects contain context attributes that describe what you know about that context, such as their name, location,
+ * device type, or organization they are associated with.
+ *
+ * You can manage how contexts interact with your app by targeting flag variations to specific contexts, based on
+ * their context attributes. When a flag evaluation occurs, the feature flag uses the evaluation context to understand
+ * what variation to serve. You can be as specific as targeting a flag to a single end context, or as broad as targeting
+ * your entire customer base. You can even use anonymous contexts and private attributes to control what data to
+ * include or exclude in the information you collect about your end users.
+ *
+ * LDContext is the newer replacement for the previous, less flexible LDUser type. The current SDK still supports
+ * LDUser, but LDContext is now the preferred model.
+ *
+ * See {@link LDSingleKindContext} and {@link LDMultiKindContext} for examples.  {@link LDContextCommon} includes
+ * additional propert
  */
 export type LDContext = LDUser | LDSingleKindContext | LDMultiKindContext;

packages/shared/common/src/api/context/LDContextCommon.ts

@@ -1,5 +1,8 @@
 import { LDContextMeta } from './LDContextMeta';
 
+/**
+ * Common attributes shared by the various context types.
+ */
 export interface LDContextCommon {
   /**
    * A unique string identifying a context.

packages/shared/common/src/api/platform/AutoEnv.ts

@@ -6,8 +6,6 @@
  * model, operating system, locale, and so on. We recommend enabling this when you configure the SDK. To learn more,
  * read [Automatic environment attributes](https://docs.launchdarkly.com/sdk/features/environment-attributes).
  * for more documentation.
- *
- * The default is disabled.
  */
 export enum AutoEnvAttributes {
   Disabled,

packages/shared/sdk-client/src/api/integrations/Hooks.ts

@@ -6,11 +6,17 @@ import { LDEvaluationDetail } from '../LDEvaluationDetail';
  * Contextual information provided to evaluation stages.
  */
 export interface EvaluationSeriesContext {
+  /**
+   * The flag key the evaluation is for.
+   */
   readonly flagKey: string;
   /**
    * Optional in case evaluations are performed before a context is set.
    */
   readonly context?: LDContext;
+  /**
+   * The default value that was provided.
+   */
   readonly defaultValue: unknown;
 
   /**
@@ -33,13 +39,19 @@ export interface EvaluationSeriesData {
  * Meta-data about a hook implementation.
  */
 export interface HookMetadata {
+  /**
+   * Name of the hook.
+   */
   readonly name: string;
 }
 
 /**
- * Contextual information provided to evaluation stages.
+ * Contextual information provided to identify stages.
  */
 export interface IdentifySeriesContext {
+  /**
+   * The context associated with the identify operation.
+   */
   readonly context: LDContext;
   /**
    * The timeout, in seconds, associated with the identify operation.
@@ -48,7 +60,7 @@ export interface IdentifySeriesContext {
 }
 
 /**
- * Implementation specific hook data for evaluation stages.
+ * Implementation specific hook data for identify stages.
  *
  * Hook implementations can use this to store data needed between stages.
  */
@@ -58,13 +70,20 @@ export interface IdentifySeriesData {
 
 /**
  * The status an identify operation completed with.
+ *
+ * An example in which an error may occur is lack of network connectivity
+ * preventing the SDK from functioning.
  */
 export type IdentifySeriesStatus = 'completed' | 'error';
 
 /**
  * The result applies to a single identify operation. An operation may complete
  * with an error and then later complete successfully. Only the first completion
- * will be executed in the evaluation series.
+ * will be executed in the identify series.
+ *
+ * For example, a network issue may cause an identify to error since the SDK
+ * can't refresh its cached data from the cloud at that moment, but then later
+ * the when the network issue is resolved, the SDK will refresh cached data.
  */
 export interface IdentifySeriesResult {
   status: IdentifySeriesStatus;