Cache docs URL; updated docstrings
diff --git a/lib/streamlit/runtime/caching/__init__.py b/lib/streamlit/runtime/caching/__init__.py
index 0550b47b8947..8f02e82363d2 100644
--- a/lib/streamlit/runtime/caching/__init__.py
+++ b/lib/streamlit/runtime/caching/__init__.py
@@ -32,8 +32,7 @@
 )
 from streamlit.runtime.state.session_state import WidgetMetadata
 
-# TODO: replace this with the proper URL once it's ready from the docs team
-CACHE_DOCS_URL = "https://NEED.CACHE.DOCS.URL"
+CACHE_DOCS_URL = "https://docs.streamlit.io/library/advanced-features/caching"
 
 
 def save_element_message(
diff --git a/lib/streamlit/runtime/caching/cache_data_api.py b/lib/streamlit/runtime/caching/cache_data_api.py
index ec21aaaf4663..5c31fd220a86 100644
--- a/lib/streamlit/runtime/caching/cache_data_api.py
+++ b/lib/streamlit/runtime/caching/cache_data_api.py
@@ -250,8 +250,8 @@ def __call__(
         *,
         ttl: float | timedelta | None = None,
         max_entries: int | None = None,
-        persist: CachePersistType | bool = None,
         show_spinner: bool | str = True,
+        persist: CachePersistType | bool = None,
         experimental_allow_widgets: bool = False,
     ) -> Callable[[F], F]:
         ...
@@ -262,8 +262,8 @@ def __call__(
         *,
         ttl: float | timedelta | None = None,
         max_entries: int | None = None,
-        persist: CachePersistType | bool = None,
         show_spinner: bool | str = True,
+        persist: CachePersistType | bool = None,
         experimental_allow_widgets: bool = False,
     ):
         return self._decorator(
@@ -281,18 +281,22 @@ def _decorator(
         *,
         ttl: float | timedelta | None,
         max_entries: int | None,
-        persist: CachePersistType | bool,
         show_spinner: bool | str,
+        persist: CachePersistType | bool,
         experimental_allow_widgets: bool,
     ):
-        """Function decorator to cache function executions.
+        """Decorator to cache functions that return data (e.g. dataframe transforms,
+        database queries, ML inference).
 
-        Cached data is stored in "pickled" form, which means that the return
-        value of a cached function must be pickleable.
+        Cached objects are stored in "pickled" form, which means that the return
+        value of a cached function must be pickleable. Each caller of the cached
+        function gets its own copy of the cached data.
 
-        Each caller of the cached function gets its own copy of the cached data.
+        You can clear a function's cache with `func.clear()` or clear the entire
+        cache with `st.cache_data.clear()`.
 
-        You can clear a cached function's cache with f.clear().
+        To cache global resources, use `st.cache_resource` instead.
+        Learn more about caching at [https://docs.streamlit.io/library/advanced-features/caching](https://docs.streamlit.io/library/advanced-features/caching)
 
         Parameters
         ----------
@@ -310,15 +314,15 @@ def _decorator(
             for an unbounded cache. (When a new entry is added to a full cache,
             the oldest cached entry will be removed.) The default is None.
 
+        show_spinner : boolean
+            Enable the spinner. Default is True to show a spinner when there is
+            a cache miss.
+
         persist : str or boolean or None
             Optional location to persist cached data to. Passing "disk" (or True)
             will persist the cached data to the local disk. None (or False) will disable
             persistence. The default is None.
 
-        show_spinner : boolean
-            Enable the spinner. Default is True to show a spinner when there is
-            a cache miss.
-
         experimental_allow_widgets : boolean
             Allow widgets to be used in the cached function. Defaults to False.
             Support for widgets in cached functions is currently experimental.
diff --git a/lib/streamlit/runtime/caching/cache_resource_api.py b/lib/streamlit/runtime/caching/cache_resource_api.py
index 6b8549d5d5e5..94fe40bc65f8 100644
--- a/lib/streamlit/runtime/caching/cache_resource_api.py
+++ b/lib/streamlit/runtime/caching/cache_resource_api.py
@@ -269,16 +269,19 @@ def _decorator(
         validate: ValidateFunc | None,
         experimental_allow_widgets: bool,
     ):
-        """Function decorator to store cached resources.
+        """Decorator to cache functions that return global resources (e.g.
+        database connections, ML models).
 
-        Each cache_resource object is shared across all users connected to the app.
-        Cached resources *must* be thread-safe, because they can be accessed from
-        multiple threads concurrently.
+        Cached objects are shared across all users, sessions, and reruns. They
+        must be thread-safe because they can be accessed from multiple threads
+        concurrently. If thread safety is an issue, consider using `st.session_state`
+        to store resources per session instead.
 
-        (If thread-safety is an issue, consider using ``st.session_state`` to
-        store per-session cached resources instead.)
+        You can clear a function's cache with `func.clear()` or clear the entire
+        cache with `st.cache_resource.clear()`.
 
-        You can clear a cache_resource function's cache with f.clear().
+        To cache data, use `st.cache_data` instead.
+        Learn more about caching at [https://docs.streamlit.io/library/advanced-features/caching](https://docs.streamlit.io/library/advanced-features/caching)
 
         Parameters
         ----------
@@ -301,12 +304,12 @@ def _decorator(
             value of show_spinner param will be used for spinner text.
 
         validate : callable or None
-            validate (callable): An optional validation function for cached data.
-            `validate` is called each time the cached value is accessed. It receives
-            the cached value as its only parameter and it must return a boolean.
-            If `validate` returns False, the current cached value is discarded, and
-            the decorated function is called to compute a new value.
-            This is useful e.g. to check the health of database connections.
+            An optional validation function for cached data. `validate` is called
+            each time the cached value is accessed. It receives the cached value as
+            its only parameter and it must return a boolean. If `validate` returns
+            False, the current cached value is discarded, and the decorated function
+            is called to compute a new value. This is useful e.g. to check the
+            health of database connections.
 
         experimental_allow_widgets : boolean
             Allow widgets to be used in the cached function. Defaults to False.
diff --git a/lib/tests/streamlit/runtime/caching/cache_data_api_test.py b/lib/tests/streamlit/runtime/caching/cache_data_api_test.py
index b1ac2ecde3f7..375141ce4184 100644
--- a/lib/tests/streamlit/runtime/caching/cache_data_api_test.py
+++ b/lib/tests/streamlit/runtime/caching/cache_data_api_test.py
@@ -137,7 +137,7 @@ def test_deprecation_warnings(
         """We show deprecation warnings when using `@st.experimental_memo`, but not `@st.cache_data`."""
         warning_str = (
             "`st.experimental_memo` is deprecated. Please use the new command `st.cache_data` instead, "
-            "which has the same behavior. More information [in our docs](https://NEED.CACHE.DOCS.URL)."
+            "which has the same behavior. More information [in our docs](https://docs.streamlit.io/library/advanced-features/caching)."
         )
 
         # We show the deprecation warning at declaration time:
diff --git a/lib/tests/streamlit/runtime/caching/cache_resource_api_test.py b/lib/tests/streamlit/runtime/caching/cache_resource_api_test.py
index 0b3458197aad..b2d6a15ffc64 100644
--- a/lib/tests/streamlit/runtime/caching/cache_resource_api_test.py
+++ b/lib/tests/streamlit/runtime/caching/cache_resource_api_test.py
@@ -108,7 +108,7 @@ def test_deprecation_warnings(
         """We show deprecation warnings when using `@st.experimental_singleton`, but not `@st.cache_resource`."""
         warning_str = (
             "`st.experimental_singleton` is deprecated. Please use the new command `st.cache_resource` instead, "
-            "which has the same behavior. More information [in our docs](https://NEED.CACHE.DOCS.URL)."
+            "which has the same behavior. More information [in our docs](https://docs.streamlit.io/library/advanced-features/caching)."
         )
 
         # We show the deprecation warning at declaration time:
diff --git a/lib/tests/streamlit/runtime/legacy_caching/caching_test.py b/lib/tests/streamlit/runtime/legacy_caching/caching_test.py
index 711569553967..d7e2c761604a 100644
--- a/lib/tests/streamlit/runtime/legacy_caching/caching_test.py
+++ b/lib/tests/streamlit/runtime/legacy_caching/caching_test.py
@@ -640,7 +640,7 @@ def func():
             "`st.cache` is deprecated. Please use one of Streamlit's new caching commands,\n"
             "`st.cache_data` or `st.cache_resource`. Based on this function's return value\n"
             "of type `int`, we recommend using `st.cache_data`.\n\n"
-            "More information [in our docs](https://NEED.CACHE.DOCS.URL)."
+            "More information [in our docs](https://docs.streamlit.io/library/advanced-features/caching)."
         )
         show_deprecation_warning.assert_called_once_with(expected_message)
 
@@ -662,7 +662,7 @@ def func():
         expected_message = (
             "`st.cache` is deprecated. Please use one of Streamlit's new caching commands,\n"
             "`st.cache_data` or `st.cache_resource`.\n\n"
-            "More information [in our docs](https://NEED.CACHE.DOCS.URL)."
+            "More information [in our docs](https://docs.streamlit.io/library/advanced-features/caching)."
         )
         show_deprecation_warning.assert_called_once_with(expected_message)
 

- Replace our placeholder `CACHE_DOCS_URL` with the proper URL
- Update `cache_data` and `cache_resource` docstrings, per product
- `cache_data`: swap the order of the `show_spinner` + `persist` kwargs, per product