DataDog / browser-sdk

Datadog Browser SDK
Apache License 2.0
305 stars 134 forks source link

Annotated TypeScript with JSDoc #1531

Open elstgav opened 2 years ago

elstgav commented 2 years ago

It would be very helpful to consumers if the TypeScript for configuration options was annotated.

For example, in my own app, I added JSDoc comments based off the Configuration documentation. (See below).

These JSDoc comments are picked up IDEs like VSCode, which is extremely useful when working with third-party plugins :+1:

interface AnnotatedConfiguration extends RumInitConfiguration {
  /**
   * The RUM application ID.
   */
  applicationId: RumInitConfiguration['applicationId']

  /**
   * A [Datadog client token](https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens).
   */
  clientToken: RumInitConfiguration['clientToken']

  /**
   * The Datadog site of your organization, same value as [agent site configuration](https://docs.datadoghq.com/agent/basic_agent_usage#datadog-site).
   *
   * @default datadoghq.com
   */
  site: RumInitConfiguration['site']

  /**
   * The service name for your application. It should follow the [tag syntax requirements](https://docs.datadoghq.com/getting_started/tagging/#defining-tags).
   */
  service?: RumInitConfiguration['service']

  /**
   * The application’s environment, for example: prod, pre-prod, staging, etc. It should follow the [tag syntax requirements](https://docs.datadoghq.com/getting_started/tagging/#defining-tags).
   */
  env?: RumInitConfiguration['env']

  /**
   * The application’s version, for example: 1.2.3, 6c44da20, 2020.02.13, etc. It should follow the [tag syntax requirements](https://docs.datadoghq.com/getting_started/tagging/#defining-tags).
   */
  version?: RumInitConfiguration['version']

  /**
   * Allows you to control RUM views creation. See [override default RUM view names](https://docs.datadoghq.com/real_user_monitoring/browser/modifying_data_and_context/?tab=npm#override-default-rum-view-names).
   *
   * @default false
   */
  trackViewsManually?: RumInitConfiguration['trackViewsManually']

  /**
   * Enables [automatic collection of users actions](https://docs.datadoghq.com/real_user_monitoring/browser/tracking_user_actions).
   * @default false
   */
  trackInteractions?: RumInitConfiguration['trackInteractions']

  /**
   * See [Session Replay Privacy Options](https://docs.datadoghq.com/real_user_monitoring/session_replay/privacy_options?tab=maskuserinput).
   *
   * @default mask-user-input
   */
  defaultPrivacyLevel?: RumInitConfiguration['defaultPrivacyLevel']

  /**
   * Specify your own attribute to be used to [name actions](https://docs.datadoghq.com/real_user_monitoring/browser/tracking_user_actions#declaring-a-name-for-click-actions).
   */
  actionNameAttribute?: RumInitConfiguration['actionNameAttribute']

  /**
   * The percentage of sessions to track: `100` for all, `0` for none. Only tracked sessions send RUM events. For more details about `sampleRate`, see the [sampling configuration](#browser-and-session-replay-sampling-configuration).
   *
   * @default 100
   */
  sampleRate?: RumInitConfiguration['sampleRate']

  /**
   * The percentage of tracked sessions with [Session Replay pricing](https://www.datadoghq.com/pricing/?product=real-user-monitoring#real-user-monitoring) features: `100` for all, `0` for none. For more details about `replaySampleRate`, see the [sampling configuration](#browser-and-session-replay-sampling-configuration).
   *
   * @default 100
   */
  replaySampleRate?: RumInitConfiguration['replaySampleRate']

  /**
   * Initialization fails silently if Datadog's RUM is already initialized on the page.
   *
   * @default false
   */
  silentMultipleInit?: RumInitConfiguration['silentMultipleInit']

  /**
   * Optional proxy URL (ex: https://www.proxy.com/path), see the full [proxy setup guide](https://docs.datadoghq.com/real_user_monitoring/faq/proxy_rum_data/) for more information.
   */
  proxyUrl?: RumInitConfiguration['proxyUrl']

  /**
   * A list of request origins used to inject tracing headers. See [Connect RUM and Traces](https://docs.datadoghq.com/real_user_monitoring/connect_rum_and_traces?tab=browserrum).
   */
  allowedTracingOrigins?: RumInitConfiguration['allowedTracingOrigins']
}
amortemousque commented 2 years ago

Hello @elstgav,

Thank you for your suggestion, it could indeed be helpful. We'll consider it.