From 1593d3db6f16d27bab69512bb593c95b4feda30f Mon Sep 17 00:00:00 2001
From: Ashby Thorpe <ashbythorpe@gmail.com>
Date: Sun, 13 Oct 2024 19:45:05 +0100
Subject: [PATCH] improve docs around local/global sessions

---
 R/api.R                  |  2 ++
 R/session.R              | 15 ++++++++++-----
 man/s.Rd                 |  2 ++
 man/selenider_session.Rd | 15 ++++++++++-----
 4 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/R/api.R b/R/api.R
index 94f03d9..08c231b 100644
--- a/R/api.R
+++ b/R/api.R
@@ -18,6 +18,8 @@
 #' @details
 #' Both functions allow the starting point for chains of selectors to be made
 #' more concise. Both use [get_session()] to get the global session object.
+#' If you want to pass in a session, use [find_element()]/[find_elements()]
+#' instead.
 #'
 #' @returns
 #' `s()` returns a `selenider_element` object.
diff --git a/R/session.R b/R/session.R
index 4317f4d..1bee4a4 100644
--- a/R/session.R
+++ b/R/session.R
@@ -1,9 +1,12 @@
 #' Start a session
 #'
 #' @description
-#' Create a session in selenider, setting it as the local session unless
-#' otherwise specified, allowing the session to be accessed globally in the
-#' environment where it was defined.
+#' Create a session in selenider. If you create a session in the global
+#' environment it will be made available to other functions (like
+#' [open_url()]) without having to pass it in, and will close automatically
+#' when the R session is closed. Alternatively, if it is created inside a
+#' function, it will be closed as soon as the function finishes executing. To
+#' customise this, use the `.env` and `local` arguments.
 #'
 #' @param session The package to use as a backend: either "chromote",
 #'   "selenium". By default, chromote is used, since this tends to be faster
@@ -29,11 +32,13 @@
 #'   * A list/environment containing the [selenium::SeleniumSession] object,
 #'     the Selenium server object, or both.
 #' @param local Whether to set the session as the local session object,
-#'   using [local_session()].
+#'   using [local_session()]. If this is `FALSE`, you will have to pass this
+#'   into the `session` argument of other functions (like [open_url()]), and
+#'   close the session manually using [close_session()].
 #' @param .env Passed into [local_session()], to define the
 #'   environment in which the session is used. Change this if you want to
 #'   create the session inside a function and then use it outside the
-#'   function.
+#'   function (see Examples). Use [rlang::caller_env()] in this case.
 #' @param view,selenium_manager,quiet `r lifecycle::badge("deprecated")`
 #'   Use the `options` argument instead.
 #'
diff --git a/man/s.Rd b/man/s.Rd
index 1a10244..c89546a 100644
--- a/man/s.Rd
+++ b/man/s.Rd
@@ -36,6 +36,8 @@ on the current session.
 \details{
 Both functions allow the starting point for chains of selectors to be made
 more concise. Both use \code{\link[=get_session]{get_session()}} to get the global session object.
+If you want to pass in a session, use \code{\link[=find_element]{find_element()}}/\code{\link[=find_elements]{find_elements()}}
+instead.
 }
 \examples{
 \dontshow{if (selenider::selenider_available(online = FALSE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
diff --git a/man/selenider_session.Rd b/man/selenider_session.Rd
index a9ddb55..677f4df 100644
--- a/man/selenider_session.Rd
+++ b/man/selenider_session.Rd
@@ -49,12 +49,14 @@ the Selenium server object, or both.
 }}
 
 \item{local}{Whether to set the session as the local session object,
-using \code{\link[=local_session]{local_session()}}.}
+using \code{\link[=local_session]{local_session()}}. If this is \code{FALSE}, you will have to pass this
+into the \code{session} argument of other functions (like \code{\link[=open_url]{open_url()}}), and
+close the session manually using \code{\link[=close_session]{close_session()}}.}
 
 \item{.env}{Passed into \code{\link[=local_session]{local_session()}}, to define the
 environment in which the session is used. Change this if you want to
 create the session inside a function and then use it outside the
-function.}
+function (see Examples). Use \code{\link[rlang:stack]{rlang::caller_env()}} in this case.}
 
 \item{view, selenium_manager, quiet}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
 Use the \code{options} argument instead.}
@@ -64,9 +66,12 @@ A \code{selenider_session} object. Use \code{session$driver} to retrieve the dri
 object that controls the browser.
 }
 \description{
-Create a session in selenider, setting it as the local session unless
-otherwise specified, allowing the session to be accessed globally in the
-environment where it was defined.
+Create a session in selenider. If you create a session in the global
+environment it will be made available to other functions (like
+\code{\link[=open_url]{open_url()}}) without having to pass it in, and will close automatically
+when the R session is closed. Alternatively, if it is created inside a
+function, it will be closed as soon as the function finishes executing. To
+customise this, use the \code{.env} and \code{local} arguments.
 }
 \section{Useful session-specific options}{
 See \code{\link[=chromote_options]{chromote_options()}} and \code{\link[=selenium_options]{selenium_options()}} for the full range.