📝 improve API documentation (#3894)

thomas-lebeau · BenoitZugmeyer · web-flow · commit 23438ff474ab · 2025-10-07T11:29:00.000+02:00
Co-authored-by: Benoit Zugmeyer &lt;benoit.zugmeyer@datadoghq.com&gt;
diff --git a/packages/logs/src/boot/logsPublicApi.ts b/packages/logs/src/boot/logsPublicApi.ts
@@ -33,7 +33,7 @@ export interface LoggerConfiguration {
  *
  * See [Browser Log Collection](https://docs.datadoghq.com/logs/log_collection/javascript) for further information.
  *
- * @category API
+ * @category Main
  */
 export interface LogsPublicApi extends PublicApi {
   /**
diff --git a/packages/logs/src/domain/configuration.ts b/packages/logs/src/domain/configuration.ts
@@ -15,14 +15,23 @@ import type { LogsEventDomainContext } from '../domainContext.types'
 /**
  * Init Configuration for the Logs browser SDK.
  *
- * @category Configuration
- * @example
+ * @category Main
+ * @example NPM
+ * ```ts
+ * import { datadogLogs } from '@datadog/browser-logs'
+ *
+ * datadogLogs.init({
+ *   clientToken: '<DATADOG_CLIENT_TOKEN>',
+ *   site: '<DATADOG_SITE>',
+ *   // ...
+ * })
+ * ```
+ * @example CDN
  * ```ts
  * DD_LOGS.init({
- *   applicationId: '<DATADOG_APPLICATION_ID>',
  *   clientToken: '<DATADOG_CLIENT_TOKEN>',
  *   site: '<DATADOG_SITE>',
- *   ...
+ *   // ...
  * })
  * ```
  */
diff --git a/packages/logs/src/entries/main.ts b/packages/logs/src/entries/main.ts
@@ -16,7 +16,7 @@ export type { InternalContext } from '../domain/contexts/internalContext'
 export type { LogsMessage } from '../domain/logger'
 export { Logger, HandlerType } from '../domain/logger'
 export { StatusType } from '../domain/logger/isAuthorized'
-export type { LoggerConfiguration, LogsPublicApi as LogsGlobal } from '../boot/logsPublicApi'
+export type { LoggerConfiguration, LogsPublicApi as DatadogLogs } from '../boot/logsPublicApi'
 export type { LogsInitConfiguration } from '../domain/configuration'
 export type { LogsEvent } from '../logsEvent.types'
 export type {
@@ -26,6 +26,11 @@ export type {
   LoggerLogsEventDomainContext,
 } from '../domainContext.types'
 
+/**
+ * @deprecated Use {@link DatadogLogs} instead
+ */
+export type LogsGlobal = LogsPublicApi
+
 export type {
   InitConfiguration,
   PublicApi,
@@ -48,6 +53,8 @@ export type {
 /**
  * The global Logs instance. Use this to call Logs methods.
  *
+ * @category Main
+ * @see {@link DatadogLogs}
  * @see [Browser Log Collection](https://docs.datadoghq.com/logs/log_collection/javascript/)
  */
 export const datadogLogs = makeLogsPublicApi(startLogs)
diff --git a/packages/rum-core/src/boot/rumPublicApi.ts b/packages/rum-core/src/boot/rumPublicApi.ts
@@ -63,7 +63,7 @@ export interface StartRecordingOptions {
  *
  * See [RUM Browser Monitoring Setup](https://docs.datadoghq.com/real_user_monitoring/browser) for further information.
  *
- * @category API
+ * @category Main
  */
 export interface RumPublicApi extends PublicApi {
   /**
@@ -73,20 +73,13 @@ export interface RumPublicApi extends PublicApi {
    *
    * @category Init
    * @param initConfiguration - Configuration options of the SDK
-   * @example Init RUM Browser SDK example
+   * @example
    * ```ts
    * datadogRum.init({
    *   applicationId: '<DATADOG_APPLICATION_ID>',
    *   clientToken: '<DATADOG_CLIENT_TOKEN>',
    *   site: '<DATADOG_SITE>',
-   *   //  service: 'my-web-application',
-   *   //  env: 'production',
-   *   //  version: '1.0.0',
-   *   sessionSampleRate: 100,
-   *   sessionReplaySampleRate: 100,
-   *   trackResources: true,
-   *   trackLongTasks: true,
-   *   trackUserInteractions: true,
+   *   // ...
    * })
    * ```
    */
@@ -158,6 +151,7 @@ export interface RumPublicApi extends PublicApi {
    * Get the init configuration
    *
    * @category Init
+   * @returns RumInitConfiguration | undefined
    */
   getInitConfiguration: () => RumInitConfiguration | undefined
 
@@ -434,30 +428,33 @@ export interface RumPublicApi extends PublicApi {
   stopDurationVital: (nameOrRef: string | DurationVitalReference, options?: DurationVitalOptions) => void
 
   /**
-   * [Experimental] start a feature operation
+   * start a feature operation
    *
    * @category Vital - Feature Operation
    * @param name - Name of the operation step
    * @param options - Options for the operation step (operationKey, context, description)
+   * @hidden // TODO: replace by @since when GA
    */
   startFeatureOperation: (name: string, options?: FeatureOperationOptions) => void
 
   /**
-   * [Experimental] succeed a feature operation
+   * succeed a feature operation
    *
    * @category Vital - Feature Operation
    * @param name - Name of the operation step
    * @param options - Options for the operation step (operationKey, context, description)
+   * @hidden // TODO: replace by @since when GA
    */
   succeedFeatureOperation: (name: string, options?: FeatureOperationOptions) => void
 
   /**
-   * [Experimental] fail a feature operation
+   * fail a feature operation
    *
    * @category Vital - Feature Operation
    * @param name - Name of the operation step
    * @param failureReason
    * @param options - Options for the operation step (operationKey, context, description)
+   * @hidden // TODO: replace by @since when GA
    */
   failFeatureOperation: (name: string, failureReaon: FailureReason, options?: FeatureOperationOptions) => void
 }
diff --git a/packages/rum-core/src/domain/configuration/configuration.ts b/packages/rum-core/src/domain/configuration/configuration.ts
@@ -23,8 +23,19 @@ export const DEFAULT_PROPAGATOR_TYPES: PropagatorType[] = ['tracecontext', 'data
 /**
  * Init Configuration for the RUM browser SDK.
  *
- * @category Configuration
- * @example
+ * @category Main
+ * @example NPM
+ * ```ts
+ * import { datadogRum } from '@datadog/browser-rum'
+ *
+ * datadogRum.init({
+ *   applicationId: '<DATADOG_APPLICATION_ID>',
+ *   clientToken: '<DATADOG_CLIENT_TOKEN>',
+ *   site: '<DATADOG_SITE>',
+ *   // ...
+ * })
+ * ```
+ * @example CDN
  * ```ts
  * DD_RUM.init({
  *   applicationId: '<DATADOG_APPLICATION_ID>',
diff --git a/packages/rum-react/react-router-v6/package.json b/packages/rum-react/react-router-v6/package.json
@@ -1,4 +1,5 @@
 {
+  "name": "@datadog/browser-rum-react/react-router-v6",
   "private": true,
   "main": "../cjs/entries/reactRouterV6.js",
   "module": "../esm/entries/reactRouterV6.js",
diff --git a/packages/rum-react/react-router-v6/typedoc.json b/packages/rum-react/react-router-v6/typedoc.json
@@ -0,0 +1,4 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["../src/entries/reactRouterV6.ts"]
+}
diff --git a/packages/rum-react/react-router-v7/package.json b/packages/rum-react/react-router-v7/package.json
@@ -1,4 +1,5 @@
 {
+  "name": "@datadog/browser-rum-react/react-router-v7",
   "private": true,
   "main": "../cjs/entries/reactRouterV7.js",
   "module": "../esm/entries/reactRouterV7.js",
diff --git a/packages/rum-react/react-router-v7/typedoc.json b/packages/rum-react/react-router-v7/typedoc.json
@@ -0,0 +1,4 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["../src/entries/reactRouterV7.ts"]
+}
diff --git a/packages/rum-react/src/domain/error/addReactError.ts b/packages/rum-react/src/domain/error/addReactError.ts
@@ -12,6 +12,26 @@ import {
 import { RumEventType } from '@datadog/browser-rum-core'
 import { onRumStart } from '../reactPlugin'
 
+/**
+ * Add a React error to the RUM session.
+ *
+ * @category Error
+ * @example
+ * ```ts
+ * import { createRoot } from 'react-dom/client'
+ * import { datadogRum } from '@datadog/browser-rum'
+ * import { addReactError } from '@datadog/browser-rum-react'
+ *
+ * const container = document.getElementById('root')
+ * const root = createRoot(container, {
+ *   onUncaughtError: (error, errorInfo) => {
+ *     // Report uncaught errors to Datadog
+ *     addReactError(error, errorInfo)
+ *   }
+ * })
+ * // ...
+ * ```
+ */
 export function addReactError(error: Error, info: ErrorInfo) {
   const handlingStack = createHandlingStack('react error')
   const startClocks = clocksNow()
diff --git a/packages/rum-react/src/domain/error/errorBoundary.spec.tsx b/packages/rum-react/src/domain/error/errorBoundary.spec.tsx
@@ -5,10 +5,10 @@ import { RumEventType } from '@datadog/browser-rum-core'
 import { disableJasmineUncaughtExceptionTracking, ignoreConsoleLogs } from '../../../../core/test'
 import { appendComponent } from '../../../test/appendComponent'
 import { initializeReactPlugin } from '../../../test/initializeReactPlugin'
-import type { Fallback } from './errorBoundary'
+import type { ErrorBoundaryFallback } from './errorBoundary'
 import { ErrorBoundary } from './errorBoundary'
 
-type FallbackFunctionComponent = Extract<Fallback, (...args: any[]) => any>
+type FallbackFunctionComponent = Extract<ErrorBoundaryFallback, (...args: any[]) => any>
 
 describe('ErrorBoundary', () => {
   beforeEach(() => {
diff --git a/packages/rum-react/src/domain/error/errorBoundary.ts b/packages/rum-react/src/domain/error/errorBoundary.ts
@@ -2,12 +2,12 @@ import React from 'react'
 import type { ErrorInfo } from 'react'
 import { addReactError } from './addReactError'
 
-export interface Props {
-  fallback: Fallback
+export interface ErrorBoundaryProps {
+  fallback: ErrorBoundaryFallback
   children: React.ReactNode
 }
 
-export type Fallback = React.ComponentType<{ error: Error; resetError: () => void }>
+export type ErrorBoundaryFallback = React.ComponentType<{ error: Error; resetError: () => void }>
 
 export type State =
   | {
@@ -21,9 +21,24 @@ export type State =
 
 const INITIAL_STATE: State = { didCatch: false, error: null }
 
+/**
+ * ErrorBoundary component to report React errors to Datadog.
+ *
+ * For more advanced error handling, you can use the {@link addReactError} function.
+ *
+ * @category Error
+ * @example
+ * ```ts
+ * import { ErrorBoundary } from '@datadog/browser-rum-react'
+ *
+ * <ErrorBoundary fallback={() => null}>
+ *   <Component />
+ * </ErrorBoundary>
+ * ```
+ */
 // eslint-disable-next-line no-restricted-syntax
-export class ErrorBoundary extends React.Component<Props, State> {
-  constructor(props: Props) {
+export class ErrorBoundary extends React.Component<ErrorBoundaryProps, State> {
+  constructor(props: ErrorBoundaryProps) {
     super(props)
     this.state = INITIAL_STATE
   }
diff --git a/packages/rum-react/src/domain/error/index.ts b/packages/rum-react/src/domain/error/index.ts
@@ -1,3 +1,3 @@
 export { ErrorBoundary } from './errorBoundary'
-export type { State, Fallback, Props } from './errorBoundary'
+export type { State, ErrorBoundaryFallback, ErrorBoundaryProps } from './errorBoundary'
 export { addReactError } from './addReactError'
diff --git a/packages/rum-react/src/domain/reactPlugin.ts b/packages/rum-react/src/domain/reactPlugin.ts
@@ -11,10 +11,16 @@ const onRumStartSubscribers: StartSubscriber[] = []
 
 /**
  * React plugin configuration.
+ *
+ * @category Main
  */
 export interface ReactPluginConfiguration {
   /**
-   * Enable react-router integration
+   * Enable react-router integration. Make sure to use functions from
+   * {@link @datadog/browser-rum-react/react-router-v6! | @datadog/browser-rum-react/react-router-v6} or
+   * {@link @datadog/browser-rum-react/react-router-v7! | @datadog/browser-rum-react/react-router-v7}
+   * to create the router.
+   * ```
    */
   router?: boolean
 }
@@ -30,6 +36,21 @@ export type ReactPlugin = Required<RumPlugin>
 
 /**
  * React plugin constructor.
+ *
+ * @category Main
+ * @example
+ * ```ts
+ * import { datadogRum } from '@datadog/browser-rum'
+ * import { reactPlugin } from '@datadog/browser-rum-react'
+ *
+ * datadogRum.init({
+ *   applicationId: '<DATADOG_APPLICATION_ID>',
+ *   clientToken: '<DATADOG_CLIENT_TOKEN>',
+ *   site: '<DATADOG_SITE>',
+ *   plugins: [reactPlugin()],
+ *   // ...
+ * })
+ * ```
  */
 export function reactPlugin(configuration: ReactPluginConfiguration = {}): ReactPlugin {
   return {
diff --git a/packages/rum-react/src/domain/reactRouter/routesComponent.ts b/packages/rum-react/src/domain/reactRouter/routesComponent.ts
@@ -5,7 +5,7 @@ export function createRoutesComponent<Location extends AnyLocation>(
   useRoutes: AnyUseRoute<Location>,
   createRoutesFromChildren: (children: React.ReactNode, parentPath?: number[]) => AnyRouteObject[]
 ) {
-  return function Routes({ children, location }: { children: React.ReactNode; location?: Location }) {
+  return function Routes({ children, location }: { children?: React.ReactNode; location?: Location }) {
     return useRoutes(createRoutesFromChildren(children), location)
   }
 }
diff --git a/packages/rum-react/src/domain/reactRouter/types.ts b/packages/rum-react/src/domain/reactRouter/types.ts
@@ -18,7 +18,7 @@ export interface AnyRouteMatch {
   route: AnyRouteObject
   params: Record<string, string | undefined>
 }
-export type AnyLocation = { pathname: string } | string
+export type AnyLocation = { pathname?: string } | string
 export type AnyCreateRouter<Options> = (
   routes: AnyRouteObject[],
   options?: Options
diff --git a/packages/rum-react/src/entries/main.ts b/packages/rum-react/src/entries/main.ts
@@ -1,6 +1,18 @@
+import type { ErrorBoundaryProps, ErrorBoundaryFallback } from '../domain/error'
+
 export { ErrorBoundary, addReactError } from '../domain/error'
-export type { State, Fallback, Props } from '../domain/error'
+export type { ErrorBoundaryFallback, ErrorBoundaryProps } from '../domain/error'
 export type { ReactPluginConfiguration, ReactPlugin } from '../domain/reactPlugin'
 export { reactPlugin } from '../domain/reactPlugin'
 // eslint-disable-next-line camelcase
 export { UNSTABLE_ReactComponentTracker } from '../domain/performance'
+
+/**
+ * @deprecated Use {@link ErrorBoundaryProps} instead.
+ */
+export type Props = ErrorBoundaryProps
+
+/**
+ * @deprecated Use {@link ErrorBoundaryFallback} instead.
+ */
+export type Fallback = ErrorBoundaryFallback
diff --git a/packages/rum-react/src/entries/reactRouterV6.ts b/packages/rum-react/src/entries/reactRouterV6.ts
diff --git a/packages/rum-react/src/entries/reactRouterV7.ts b/packages/rum-react/src/entries/reactRouterV7.ts
diff --git a/packages/rum-react/typedoc.json b/packages/rum-react/typedoc.json
diff --git a/packages/rum-slim/src/entries/main.ts b/packages/rum-slim/src/entries/main.ts
diff --git a/packages/rum/src/entries/main.ts b/packages/rum/src/entries/main.ts
diff --git a/typedoc.json b/typedoc.json

Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@ export interface LoggerConfiguration {`
`33`	`33`	`*`
`34`	`34`	`* See [Browser Log Collection](https://docs.datadoghq.com/logs/log_collection/javascript) for further information.`
`35`	`35`	`*`
`36`		`- * @category API`
	`36`	`+ * @category Main`
`37`	`37`	`*/`
`38`	`38`	`export interface LogsPublicApi extends PublicApi {`
`39`	`39`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`{`
	`2`	`+ "name": "@datadog/browser-rum-react/react-router-v6",`
`2`	`3`	`"private": true,`
`3`	`4`	`"main": "../cjs/entries/reactRouterV6.js",`
`4`	`5`	`"module": "../esm/entries/reactRouterV6.js",`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +{
 +  "$schema": "https://typedoc.org/schema.json",
 +  "entryPoints": ["../src/entries/reactRouterV6.ts"]
 +}