ref(javascript): Improve beforeSendSpan documentation (#10907)

docs/platforms/javascript/common/configuration/filtering.mdx

@@ -213,13 +213,15 @@ If the transaction currently being processed has a parent transaction (from an u
 
 Learn more about <PlatformLink to="/configuration/sampling/">configuring the sample rate</PlatformLink>.
 
-### Using <PlatformIdentifier name="before-send-transaction" />
+### Using `beforeSendTransaction`
 
 <PlatformContent includePath="configuration/before-send-transaction" />
 
 ## Filtering Spans
 
-To prevent certain spans from being reported to Sentry, use the <PlatformIdentifier name="before-send-span" /> configuration option, which allows you to provide a function to evaluate the current span and drop it if it's not one you want.
-This API is available from Javascript SDK version 8.2.0 and above.
+Available since Javascript SDK version `8.2.0`.
+
+To prevent certain spans from being reported to Sentry, use the <PlatformIdentifier name="before-send-span" /> configuration option which allows you to provide a function to modify and drop a child span.
+This function is only called for child spans of the root span. If you want to modify or drop the root span, including its child spans, use [`beforeSendTransaction`](#using-beforesendtransaction) instead.
 
 <PlatformContent includePath="configuration/before-send-span" />

docs/platforms/javascript/common/configuration/options.mdx

@@ -293,20 +293,20 @@ This function is called with an SDK-specific transaction event object, and can r
 
 </ConfigKey>
 
-<ConfigKey name="before-breadcrumb">
+<ConfigKey name="before-send-span">
 
-This function is called with an SDK-specific breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the first argument, which contains the breadcrumb object.
-The callback typically gets a second argument (called a "hint") which contains the original object from which the breadcrumb was created to further customize what the breadcrumb should look like.
+This function is called with a serialized span object, and can return a modified span object, or `null` to skip sending the span. This might be useful for manually stripping PII from spans or to remove individual spans from the span tree.
+This function is only called for child spans of the root span. If you want to modify or drop the root span, including all of its child spans, use [`beforeSendTransaction`](#before-send-transaction) instead.
 
 </ConfigKey>
 
-<ConfigKey name="before-send-span">
+<ConfigKey name="before-breadcrumb">
 
-This function is called with an SDK-specific span object, and can return a modified span object, or `null` to skip reporting the span. One way this might be used is for manual PII stripping before sending.
+This function is called with an SDK-specific breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the first argument, which contains the breadcrumb object.
+The callback typically gets a second argument (called a "hint") which contains the original object from which the breadcrumb was created to further customize what the breadcrumb should look like.
 
 </ConfigKey>
 
-
 ## Transport Options
 
 Transports are used to send events to Sentry. Transports can be customized to some degree to better support highly specific deployments.