📝 adjust Public Api and Init configuration categories (#3855)

Author: BenoitZugmeyer

packages/core/src/domain/configuration/configuration.ts

@@ -51,24 +51,34 @@ export type TraceContextInjection = (typeof TraceContextInjection)[keyof typeof
 export interface InitConfiguration {
   /**
    * The client token for Datadog. Required for authenticating your application with Datadog.
+   *
+   * @category Authentication
    */
   clientToken: string
+
   /**
    * A callback function that can be used to modify events before they are sent to Datadog.
+   *
+   * @category Data Collection
    */
   beforeSend?: GenericBeforeSendCallback | undefined
+
   /**
    * The percentage of sessions tracked. A value between 0 and 100.
    *
+   * @category Data Collection
    * @defaultValue 100
    */
   sessionSampleRate?: number | undefined
+
   /**
    * The percentage of telemetry events sent. A value between 0 and 100.
    *
+   * @category Data Collection
    * @defaultValue 20
    */
   telemetrySampleRate?: number | undefined
+
   /**
    * Initialization fails silently if the RUM Browser SDK is already initialized on the page.
    *
@@ -81,6 +91,7 @@ export interface InitConfiguration {
    *
    * Important: If you are using the RUM and Logs Browser SDKs, this option must be configured with identical values
    *
+   * @category Session Persistence
    * @defaultValue "cookie"
    */
   sessionPersistence?: SessionPersistence | undefined
@@ -91,6 +102,7 @@ export interface InitConfiguration {
    * Important: If you are using the RUM and Logs Browser SDKs, this option must be configured with identical values
    * See [Monitor Electron Applications Using the Browser SDK](https://docs.datadoghq.com/real_user_monitoring/guide/monitor-electron-applications-using-browser-sdk) for further information.
    *
+   * @category Session Persistence
    * @deprecated use `sessionPersistence: local-storage` where you want to use localStorage instead
    */
   allowFallbackToLocalStorage?: boolean | undefined
@@ -101,17 +113,20 @@ export interface InitConfiguration {
    * @defaultValue false
    */
   allowUntrustedEvents?: boolean | undefined
+
   /**
    * Store global context and user context in localStorage to preserve them along the user navigation.
    * See [Contexts life cycle](https://docs.datadoghq.com/real_user_monitoring/browser/advanced_configuration/?tab=npm#contexts-life-cycle) for further information.
    *
    * @defaultValue false
    */
   storeContextsAcrossPages?: boolean | undefined
+
   /**
    * Set the initial user tracking consent state.
    * See [User tracking consent](https://docs.datadoghq.com/real_user_monitoring/browser/advanced_configuration/?tab=npm#user-tracking-consent) for further information.
    *
+   * @category Privacy
    * @defaultValue granted
    */
   trackingConsent?: TrackingConsent | undefined
@@ -127,27 +142,38 @@ export interface InitConfiguration {
   /**
    * Optional proxy URL, for example: https://www.proxy.com/path.
    * See [Proxy Your Browser RUM Data](https://docs.datadoghq.com/real_user_monitoring/guide/proxy-rum-data) for further information.
+   *
+   * @category Transport
    */
   proxy?: string | ProxyFn | undefined
+
   /**
    * The Datadog [site](https://docs.datadoghq.com/getting_started/site) parameter of your organization.
    *
+   * @category Transport
    * @defaultValue datadoghq.com
    */
   site?: Site | undefined
 
   // tag and context options
   /**
    * The service name for your application. Follows the [tag syntax requirements](https://docs.datadoghq.com/getting_started/tagging/#define-tags).
+   *
+   * @category Data Collection
    */
   service?: string | undefined | null
+
   /**
    * The application’s environment, for example: prod, pre-prod, and staging. Follows the [tag syntax requirements](https://docs.datadoghq.com/getting_started/tagging/#define-tags).
    *
+   * @category Data Collection
    */
   env?: string | undefined | null
+
   /**
    * The application’s version, for example: 1.2.3, 6c44da20, and 2020.02.13. Follows the [tag syntax requirements](https://docs.datadoghq.com/getting_started/tagging/#define-tags).
+   *
+   * @category Data Collection
    */
   version?: string | undefined | null
 
@@ -157,60 +183,77 @@ export interface InitConfiguration {
    *
    * Important: If you are using the RUM and Logs Browser SDKs, this option must be configured with identical values
    *
+   * @category Session Persistence
    * @defaultValue false
    */
   usePartitionedCrossSiteSessionCookie?: boolean | undefined
+
   /**
    * Use a secure session cookie. This disables RUM events sent on insecure (non-HTTPS) connections.
    *
    * Important: If you are using the RUM and Logs Browser SDKs, this option must be configured with identical values
    *
+   * @category Session Persistence
    * @defaultValue false
    */
   useSecureSessionCookie?: boolean | undefined
+
   /**
    * Preserve the session across subdomains for the same site.
    *
    * Important: If you are using the RUM and Logs Browser SDKs, this option must be configured with identical values
    *
+   * @category Session Persistence
    * @defaultValue false
    */
   trackSessionAcrossSubdomains?: boolean | undefined
+
   /**
    * Track anonymous user for the same site and extend cookie expiration date
    *
+   * @category Data Collection
    * @defaultValue true
    */
   trackAnonymousUser?: boolean | undefined
+
   // internal options
   /**
    * [Internal option] Enable experimental features
    *
    * @internal
    */
   enableExperimentalFeatures?: string[] | undefined
+
   /**
    * [Internal option] Configure the dual shipping to another datacenter
+   *
+   * @internal
    */
   replica?: ReplicaUserConfiguration | undefined
+
   /**
    * [Internal option] Set the datacenter from where the data is dual shipped
+   *
+   * @internal
    */
   datacenter?: string
+
   /**
    * [Internal option] Datadog internal analytics subdomain
    *
    * @internal
    */
   // TODO next major: remove this option and replace usages by proxyFn
   internalAnalyticsSubdomain?: string
+
   /**
    * [Internal option] The percentage of telemetry configuration sent. A value between 0 and 100.
    *
    * @internal
    * @defaultValue 5
    */
   telemetryConfigurationSampleRate?: number
+
   /**
    * [Internal option] The percentage of telemetry usage sent. A value between 0 and 100.
    *

packages/logs/src/boot/logsPublicApi.ts

@@ -64,7 +64,7 @@ export interface LogsPublicApi extends PublicApi {
    *
    * See [User tracking consent](https://docs.datadoghq.com/logs/log_collection/javascript/#user-tracking-consent) for further information.
    *
-   * @category Tracking Consent
+   * @category Privacy
    * @param trackingConsent - The user tracking consent
    */
   setTrackingConsent: (trackingConsent: TrackingConsent) => void
@@ -73,7 +73,7 @@ export interface LogsPublicApi extends PublicApi {
    * Set the global context information to all events, stored in `@context`
    * See [Global context](https://docs.datadoghq.com/logs/log_collection/javascript/#overwrite-context) for further information.
    *
-   * @category Global Context
+   * @category Context - Global Context
    * @param context - Global context
    */
   setGlobalContext: (context: any) => void
@@ -83,7 +83,7 @@ export interface LogsPublicApi extends PublicApi {
    *
    * See [Global context](https://docs.datadoghq.com/logs/log_collection/javascript/#overwrite-context) for further information.
    *
-   * @category Global Context
+   * @category Context - Global Context
    */
   getGlobalContext: () => Context
 
@@ -92,7 +92,7 @@ export interface LogsPublicApi extends PublicApi {
    *
    * See [Global context](https://docs.datadoghq.com/logs/log_collection/javascript/#overwrite-context) for further information.
    *
-   * @category Global Context
+   * @category Context - Global Context
    * @param key - Key of the property
    * @param value - Value of the property
    */
@@ -103,7 +103,7 @@ export interface LogsPublicApi extends PublicApi {
    *
    * See [Global context](https://docs.datadoghq.com/logs/log_collection/javascript/#overwrite-context) for further information.
    *
-   * @category Global Context
+   * @category Context - Global Context
    */
   removeGlobalContextProperty: (key: any) => void
 
@@ -112,7 +112,7 @@ export interface LogsPublicApi extends PublicApi {
    *
    * See [Global context](https://docs.datadoghq.com/logs/log_collection/javascript/#overwrite-context) for further information.
    *
-   * @category Global Context
+   * @category Context - Global Context
    */
   clearGlobalContext: () => void
 
@@ -121,15 +121,15 @@ export interface LogsPublicApi extends PublicApi {
    *
    * See [User session](https://docs.datadoghq.com/logs/log_collection/javascript/#user-context) for further information.
    *
-   * @category User
+   * @category Context - User
    * @param newUser - User information
    */
   setUser(newUser: User & { id: string }): void
 
   /**
    * Set user information to all events, stored in `@usr`
    *
-   * @category User
+   * @category Context - User
    * @deprecated You must specify a user id, favor using {@link setUser} instead
    * @param newUser - User information with optional id
    */
@@ -140,7 +140,7 @@ export interface LogsPublicApi extends PublicApi {
    *
    * See [User session](https://docs.datadoghq.com/logs/log_collection/javascript/#user-context) for further information.
    *
-   * @category User
+   * @category Context - User
    * @returns User information
    */
   getUser: () => Context
@@ -150,7 +150,7 @@ export interface LogsPublicApi extends PublicApi {
    *
    * See [User session](https://docs.datadoghq.com/logs/log_collection/javascript/#user-context) for further information.
    *
-   * @category User
+   * @category Context - User
    * @param key - Key of the property
    * @param property - Value of the property
    */
@@ -159,7 +159,7 @@ export interface LogsPublicApi extends PublicApi {
   /**
    * Remove a user property
    *
-   * @category User
+   * @category Context - User
    * @param key - Key of the property to remove
    * @see [User session](https://docs.datadoghq.com/logs/log_collection/javascript/#user-context) for further information.
    */
@@ -170,30 +170,30 @@ export interface LogsPublicApi extends PublicApi {
    *
    * See [User session](https://docs.datadoghq.com/logs/log_collection/javascript/#user-context) for further information.
    *
-   * @category User
+   * @category Context - User
    */
   clearUser: () => void
 
   /**
    * Set account information to all events, stored in `@account`
    *
-   * @category Account
+   * @category Context - Account
    * @param newAccount - Account information
    */
   setAccount: (newAccount: Account) => void
 
   /**
    * Get account information
    *
-   * @category Account
+   * @category Context - Account
    * @returns Account information
    */
   getAccount: () => Context
 
   /**
    * Set or update the account property, stored in `@account.<key>`
    *
-   * @category Account
+   * @category Context - Account
    * @param key - Key of the property
    * @param property - Value of the property
    */
@@ -202,15 +202,15 @@ export interface LogsPublicApi extends PublicApi {
   /**
    * Remove an account property
    *
-   * @category Account
+   * @category Context - Account
    * @param key - Key of the property to remove
    */
   removeAccountProperty: (key: string) => void
 
   /**
    * Clear all account information
    *
-   * @category Account
+   * @category Context - Account
    * @returns Clear all account information
    */
   clearAccount: () => void

packages/logs/src/domain/configuration.ts

@@ -33,25 +33,37 @@ export interface LogsInitConfiguration extends InitConfiguration {
    * - Enrich your logs with additional context attributes
    * - Modify your logs to modify their content, or redact sensitive sequences (see the list of editable properties)
    * - Discard selected logs
+   *
+   * @category Data Collection
    */
   beforeSend?: ((event: LogsEvent, context: LogsEventDomainContext) => boolean) | undefined
+
   /**
    * Forward console.error logs, uncaught exceptions and network errors to Datadog.
    *
+   * @category Data Collection
    * @defaultValue true
    */
   forwardErrorsToLogs?: boolean | undefined
+
   /**
    * Forward logs from console.* to Datadog. Use "all" to forward everything or an array of console API names to forward only a subset.
+   *
+   * @category Data Collection
    */
   forwardConsoleLogs?: ConsoleApiName[] | 'all' | undefined
+
   /**
    * Forward reports from the [Reporting API](https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API) to Datadog. Use "all" to forward everything or an array of report types to forward only a subset.
+   *
+   * @category Data Collection
    */
   forwardReports?: RawReportType[] | 'all' | undefined
+
   /**
    * Use PCI-compliant intake. See [PCI DSS Compliance](https://docs.datadoghq.com/data_security/pci_compliance/?tab=logmanagement) for further information.
    *
+   * @category Privacy
    * @defaultValue false
    */
   usePciIntake?: boolean

packages/logs/typedoc.json

@@ -1,4 +1,15 @@
 {
   "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["src/entries/main.ts"]
+  "entryPoints": ["src/entries/main.ts"],
+
+  "categoryOrder": [
+    "Init",
+    "Authentication",
+    "Privacy",
+    "Data Collection",
+    "Session Persistence",
+    "Transport",
+    "*",
+    "Other"
+  ]
 }