SNOW-1755655: Add a note in cache_result about table name and temp ta…

…ble cleanup (#2638)

<!---
Please answer these questions before creating your pull request. Thanks!
--->

1. Which Jira issue is this PR addressing? Make sure that there is an
accompanying issue to your PR.

   <!---
   In this section, please add a Snowflake Jira issue number.

Note that if a corresponding GitHub issue exists, you should still
include
   the Snowflake Jira issue number. For example, for GitHub issue
#1400, you should
   add "SNOW-1335071" here.
    --->

   Fixes SNOW-1755655

2. Fill out the following pre-review checklist:

- [ ] I am adding a new automated test(s) to verify correctness of my
new code
- [ ] If this test skips Local Testing mode, I'm requesting review from
@snowflakedb/local-testing
   - [ ] I am adding new logging messages
   - [ ] I am adding a new telemetry message
   - [ ] I am adding new credentials
   - [ ] I am adding a new dependency
- [ ] If this is a new feature/behavior, I'm adding the Local Testing
parity changes.
- [x] I acknowledge that I have ensured my changes to be thread-safe.
Follow the link for more information: [Thread-safe Developer
Guidelines](https://docs.google.com/document/d/162d_i4zZ2AfcGRXojj0jByt8EUq-DrSHPPnTa4QvwbA/edit#bookmark=id.e82u4nekq80k)

3. Please describe how your code solves the related issue.

This pull request includes an update to the `cache_result` method in the
`src/snowflake/snowpark/dataframe.py` file to provide additional
documentation and clarity on the behavior of the method. The most
important changes include adding a detailed note about the creation and
lifecycle of the temporary table used to store the cached result.

Documentation improvements:

*
[`src/snowflake/snowpark/dataframe.py`](diffhunk://#diff-9732895e18d0ffe66be3624d2aaefcba56260bcc238a6a0a598ef601512e03e8R4074-R4086):
Added a note explaining that a temporary table is created to store the
cached result, including details on how it may be automatically removed
and how to retain a persistent table using
`DataFrameWriter.save_as_table`.

src/snowflake/snowpark/dataframe.py

@@ -4071,6 +4071,19 @@ def cache_result(
         Returns:
              A :class:`Table` object that holds the cached result in a temporary table.
              All operations on this new DataFrame have no effect on the original.
+
+        Note:
+            A temporary table is created to store the cached result and a :class:`Table` object is returned.
+            You can retrieve the table name by accessing :attr:`Table.table_name`. Note that this temporary
+            Snowflake table
+
+                - may be automatically removed when the Table object is no longer referenced if
+                  :attr:`Session.auto_clean_up_temp_table_enabled` is set to ``True``.
+
+                - will be dropped after the session is closed.
+
+            To retain a persistent table, consider using :meth:`DataFrameWriter.save_as_table` to persist
+            the cached result.
         """
         with open_telemetry_context_manager(self.cache_result, self):
             from snowflake.snowpark.mock._connection import MockServerConnection