Use #' @examplesIf roxygen directive over if() in the docs

[IndrajeetPatil]

There are a couple of reasons to do this:

1. When there are more than two outputs in if(), only the final one will be displayed in the pkgdown website (cf. Only output from the final example is shown for examples in an if() block r-lib/pkgdown#2175).

#' @examples
#' if (getRversion() > "4.0") {
#'   sd(cars$speed)
#'   sd(cars$dist)
#' }

This is not the case if we use #' @examplesIf instead.

#' @examplesIf getRversion() > "4.0"
#' sd(cars$speed)
#' sd(cars$dist)

2. This also helps clarify all external dependencies at the top-level (which helps with Mimic and get builds to pass for CRAN's "noSuggests" check in CI/CD #317).

Progress tracker:

• insight
• modelbased
• bayestestR
• effectsize
• parameters
• performance
• correlation
• report
• see
• datawizard
• easystats

[IndrajeetPatil]

Keep in mind that if your original conditional statement was something like:

#' @examples 
if (requireNamespace("zoo", quietly = TRUE)) {
  ...
}

If you use examplesIf, this won't be included in the output, so it might be a good idea to either namespace all externally used functions, or have a library() call at the top so that the users can exactly reproduce the output.

#' @examplesIf requireNamespace("zoo", quietly = TRUE) 
library(zoo)
 ...

Thanks, @etiennebacher, for bringing up this issue.

[mattansb]

Note that in R 4.2.1, the "run examples" is still meh here...

[IndrajeetPatil]

Hmm, but this is not too bad. At least, it shows all the output. I am a bit more concerned about some of the outputs not showing up at all on the website.

---

I can create an issue in rstudio repo to check if they can handle this a bit better. Ideally, the following should not appear in the output:

## Don't show: 
## End(Don't show)
}) # examplesIf

[IndrajeetPatil]

I also checked in the PDF manual, and the examples look good.

[IndrajeetPatil]

Created issue in RStudio to track the suboptimal rendering of examples when run in the IDE: rstudio/rstudio#12318

[IndrajeetPatil]

@rempsyc It would be great if you can also resolve this for report before the next submission.

[rempsyc]

Is this necessary when the example is already wrapped in \donttest?

[IndrajeetPatil]

Yes, because CRAN tests \donttest examples in an additional check.

[IndrajeetPatil]

bump

[strengejacke]

Keep in mind that if your original conditional statement was something like:

#' @examples 
if (requireNamespace("zoo", quietly = TRUE)) {
  ...
}

If you use examplesIf, this won't be included in the output, so it might be a good idea to either namespace all externally used functions, or have a library() call at the top so that the users can exactly reproduce the output.

#' @examplesIf requireNamespace("zoo", quietly = TRUE) 
library(zoo)
 ...

Thanks, @etiennebacher, for bringing up this issue.

What about @ExamplesIf require(<package>) ?

[IndrajeetPatil]

Yepp, this is fine. In fact, it's one of the very few situations where require() usage is acceptable.

[bwiernik]

Could you explain the difference here? Not sure I'm following