From 35409a6f7841e9388ccd1822464101681022aa43 Mon Sep 17 00:00:00 2001
From: James Azam <james.azam@lshtm.ac.uk>
Date: Tue, 2 Jul 2024 14:30:26 +0100
Subject: [PATCH] Update documentation of dots in `stan_sampling_opts()` (#699)

* Dots are only passed to rstan sampling here

* Fix function hyperlink

* Update dots docs to include cmdstanr sample function

* Add NEWS

* Add reviewer and PR number
---
 NEWS.md                   | 4 ++++
 R/deprecated.R            | 1 +
 R/opts.R                  | 5 +++--
 man/stan_sampling_opts.Rd | 5 +++--
 4 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 18384c015..25e154d64 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -4,6 +4,10 @@
 
 - `epinow()` now returns the "timing" output in a "time difference"" format that is easier to understand and work with. By @jamesmbaazam in #688 and reviewed by @sbfnk.
 
+## Documentation
+
+- Updated the documentation of the dots argument of the `stan_sampling_opts()` to add that the dots are passed to `cmdstanr::sample()`. By @jamesmbaazam in #699 and reviewed by @sbfnk.
+
 # EpiNow2 1.5.2
 
 A patch release to further fix an issue with the date in the package citation. This has now been addressed by removing `inst/CITATION`.
diff --git a/R/deprecated.R b/R/deprecated.R
index 25f9a3ad3..c7928e360 100644
--- a/R/deprecated.R
+++ b/R/deprecated.R
@@ -386,6 +386,7 @@ get_incubation_period <- function(disease, source, max_value = 14,
 #'
 #' @description `r lifecycle::badge("deprecated")`
 #' Deprecated; use [stan_sampling_opts()] instead.
+#' @param ... Additional parameters to pass to [rstan::sampling()].
 #' @inheritParams stan_sampling_opts
 #' @return A list of arguments to pass to [rstan::sampling()].
 #' @export
diff --git a/R/opts.R b/R/opts.R
index 834a3b7c3..a9e7ef6f0 100644
--- a/R/opts.R
+++ b/R/opts.R
@@ -606,10 +606,11 @@ obs_opts <- function(family = c("negbin", "poisson"),
 #'
 #' @inheritParams stan_opts
 #'
-#' @param ... Additional parameters to pass to [rstan::sampling()].
+#' @param ... Additional parameters to pass to [rstan::sampling()] or
+#' [cmdstanr::sample()].
 #' @importFrom utils modifyList
 #' @return A list of arguments to pass to [rstan::sampling()] or
-#' [cmdstanr::sample().
+#' [cmdstanr::sample()].
 #' @export
 #' @examples
 #' stan_sampling_opts(samples = 2000)
diff --git a/man/stan_sampling_opts.Rd b/man/stan_sampling_opts.Rd
index 5ecfcdc8e..e1b89d466 100644
--- a/man/stan_sampling_opts.Rd
+++ b/man/stan_sampling_opts.Rd
@@ -55,11 +55,12 @@ estimation will fail with an informative error.}
 \item{backend}{Character string indicating the backend to use for fitting
 stan models. Supported arguments are "rstan" (default) or "cmdstanr".}
 
-\item{...}{Additional parameters to pass to \code{\link[rstan:stanmodel-method-sampling]{rstan::sampling()}}.}
+\item{...}{Additional parameters to pass to \code{\link[rstan:stanmodel-method-sampling]{rstan::sampling()}} or
+\code{\link[cmdstanr:model-method-sample]{cmdstanr::sample()}}.}
 }
 \value{
 A list of arguments to pass to \code{\link[rstan:stanmodel-method-sampling]{rstan::sampling()}} or
-[cmdstanr::sample().
+\code{\link[cmdstanr:model-method-sample]{cmdstanr::sample()}}.
 }
 \description{
 \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}