[R-pkg-devel] Fwd: R CMD check and strange ## Not run strings

Georgi Boshnakov georgi.boshnakov at manchester.ac.uk
Mon Dec 18 20:07:59 CET 2017


This actually is not about Rd format. Indeed, you are using   'roxygen' syntax. 

Examples are not run when there is a good reason (long time, internet connection required, specific local resources). This often means that the user needs to be made aware that something is not as straightforward as usual. 

A better question would probably be "Is there a better way to alert the user that the example is somehow special?" Maybe, but it is difficult to beat "Not run" for brevity and native English speakers would probably have come forward with a better replacement.  

Also, adding a note (in a comment before the example)  as to way an example is not run can be of benefit to both the user and the package author. Even if it is obvious at the time of writing, it may not be so months or years later.

Kind regards,
Georgi Boshnakov

-----Original Message-----
From: R-package-devel [mailto:r-package-devel-bounces at r-project.org] On Behalf Of Tomas Hudik
Sent: 18 December 2017 13:38
To: r-package-devel at r-project.org
Subject: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings

Hi there,

If I write a function with documentation (notice `\dontrun` section)

#' Print a string.
#' @examples
#' \dontrun{
#' str_length(letters)
print_str <- function(str) {

`roxygenize()` will create proper Rd file, however, `R CMD check .` will
## Not run:
## End(Not run)

If a person not familiar with Rd (majority of people) see such example, I do think he will be confused.
Question - wouldnt be good to remove `## NOT run` strings by default ( https://github.com/wch/r-source/blob/af7f52f70101960861e5d995d3a4be

E.g. see https://cran.r-project.org/web/packages/gmailr/gmailr.pdf - and go through example sections. There is not many people who would know what those cryptic `## Not Run` strings mean.

thanks, Tomas

	[[alternative HTML version deleted]]

R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel

More information about the R-package-devel mailing list