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

[Georgi Boshnakov]

… and my point was that it is not a matter of syntax, but that the user would better be alerted.

A user would be more confused and even irritated if they run an example and get surprises (such as having to wait a long time) or not getting any wiser.

The example you cite falls into the category of ‘template examples’  - it is not really meant to be run as is.
You almost certainly will never encounter message 12345, for example.   In fact, it would probably give error.  This is a nice illustration of the usefulness of ‘Not run’ to give a sort of warning.
I bet that the package you have taken it from contains similar examples in other places, so a user will become aware of this.


Merry Christmas,
Georgi



From: Tomas Hudik [mailto:xhudik at gmail.com]
Sent: 19 December 2017 16:02
To: Georgi Boshnakov
Cc: r-package-devel at r-project.org
Subject: Re: [R-pkg-devel] Fwd: R CMD check and strange ## Not run strings

Yes, I used oxygen. My point was that a majority of users is not familiar Rd/oxygen and if somebody sees something like:

```
Examples

## Not run:
modify_message(12345, add_labels='label_1')
modify_message(12345, remove_labels='label_1')
#add and remove at the same time
modify_message(12345, add_labels='label_2', remove_labels='label_1')

## End(Not run)
```
he will be pretty much confused and will not get that it is because of a special example that couldnt run for any reason.
Whether example run during package compilation might be important for package creator but not so much for a regular user.

Therefore I think the question is whether a standard user needs to know whether some code in help page run during the package compilation.

my 2c, Tomas


On Mon, Dec 18, 2017 at 8:07 PM, Georgi Boshnakov <georgi.boshnakov at manchester.ac.uk<mailto:georgi.boshnakov at manchester.ac.uk>> wrote:
Hi,

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<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<mailto: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) {
  print(string)
}

`roxygenize()` will create proper Rd file, however, `R CMD check .` will
generate:
```
...
## Not run:
str_length(letters)
## 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
c010bc89e6/src/library/tools/R/Rd2latex.R#L238
)

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<mailto:R-package-devel at r-project.org> mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel


	[[alternative HTML version deleted]]