docs: update shouldRevalidate docs

Author: ryanflorence

docs/start/data/route-object.md

@@ -139,7 +139,17 @@ export default function Items() {
 
 ## `shouldRevalidate`
 
-By default, all routes are revalidated after actions. This function allows a route to opt-out of revalidation for actions that don't affect its data.
+Loader data is automatically revalidated after certain events like navigations and form submissions.
+
+This hook enables you to opt in or out of the default revalidation behavior. The default behavior is nuanced to avoid calling loaders unnecessarily.
+
+A route loader is revalidated when:
+
+- its own route params change
+- any change to URL search params
+- after any actions are called
+
+By defining this function, you opt out of the default behavior completely and can manually control when loader data is revalidated for navigations and form submissions.
 
 ```tsx
 import type { ShouldRevalidateFunctionArgs } from "react-router";
@@ -159,6 +169,10 @@ createBrowserRouter([
 ]);
 ```
 
+[`ShouldRevalidateFunctionArgs` Reference Documentation ↗](https://api.reactrouter.com/v7/interfaces/react_router.ShouldRevalidateFunctionArgs.html)
+
+Please note the default behavior is different in [Framework Mode](../modes).
+
 ## `lazy`
 
 Most properties can be lazily imported to reduce the initial bundle size.

docs/start/framework/route-module.md

@@ -351,7 +351,9 @@ export default function Root() {
 
 ## `shouldRevalidate`
 
-By default, all routes are revalidated after actions. This function allows a route to opt-out of revalidation for actions that don't affect its data.
+In framework mode, route loaders are automatically revalidated after all navigations and form submissions (this is different from [Data Mode](../data/route-object#shouldrevalidate)). This enables middleware and loaders to share a request context and optimize in different ways than then they would be in Data Mode.
+
+Defining this function allows you to opt out of revalidation for a route loader for navigations and form submissions.
 
 ```tsx
 import type { ShouldRevalidateFunctionArgs } from "react-router";
@@ -363,6 +365,8 @@ export function shouldRevalidate(
 }
 ```
 
+[`ShouldRevalidateFunctionArgs` Reference Documentation ↗](https://api.reactrouter.com/v7/interfaces/react_router.ShouldRevalidateFunctionArgs.html)
+
 ---
 
 Next: [Rendering Strategies](./rendering)