Be more confident and informative in the comment for CRM_Core_Session::set()

diff --git a/CRM/Core/Session.php b/CRM/Core/Session.php
index fa6003c784d3d9a23361313f9aff73989263dfe5..5f5f46589e7cf0c9122c528a0acdf36e92133752 100644 (file)
--- a/CRM/Core/Session.php
+++ b/CRM/Core/Session.php
@@ -207,18 +207,18 @@ class CRM_Core_Session {
   }
 
   /**
-   * Store the variable with the value in the session scope.
-   *
-   * This function takes a name, value pair and stores this
-   * in the session scope. Not sure what happens if we try
-   * to store complex objects in the session. I suspect it
-   * is supported but we need to verify this
-   *
+   * Store a name-value pair in the session scope.
    *
    * @param string $name
    *   Name of the variable.
    * @param mixed $value
-   *   Value of the variable.
+   *   Value of the variable. It is safe to use scalar values here, as well as
+   *   arrays whose leaf nodes are scalar values. Instances of built-in classes
+   *   like DateTime may be safe, although the retrieved objects will be copies
+   *   of the ones saved here. Instances of custom classes (such as those
+   *   defined in CiviCRM core or extension code) will probably not be rebuilt
+   *   correctly on retrieval. Resources and other special variable types are
+   *   not safe to use. References will be dereferenced.
    * @param string $prefix
    *   A string to prefix the keys in the session with.
    */