Have you considered putting the explicit case into a comment? Something like ...
# For output to a CSV file, we would assign: myCSV <- "myResults.csv" # ... but for this example we will use the value of tempfile() as the file name: myCSV <- tempfile() results <- doSomething(x, csvFile = myCSV, ...) I often find the lack of comments in examples less than optimal for didactic reasons. $0.02 Boris > On 2019-05-07, at 18:50, Duncan Murdoch <murdoch.dun...@gmail.com> wrote: > > On 07/05/2019 6:44 p.m., Uwe Ligges wrote: >> On 07.05.2019 19:57, Duncan Murdoch wrote: >>> On 06/05/2019 12:16 p.m., Jim Hester wrote: >>>> For what it's worth, the recommendation to use `tempfile()` is very >>>> confusing to R users. >>>> >>>> Often users (particularly new users) jump directly to examples when >>>> reading documentation and when you have these more complicated >>>> examples they do not realize they can just use a simple string >>>> literal. >>>> >>>> See https://github.com/tidyverse/readr/issues/635 for an issue where >>>> multiple users explicitly request examples which do _not_ use >>>> `tempfile()`. >>> >>> I think beginners rarely like the help pages, and that's really to be >>> expected: help pages need to be complete and correct, and beginners >>> really need a small subset of possibilities. Beginners need tutorials. >>> >>> In the Github issue, you mentioned pollution of the working directory, >>> but I think a bigger problem is destruction of user data, e.g. if a user >>> has a file "wine.csv", and the example writes to that file. >>> >>> So you need to do something to protect users. I think making examples a >>> little complicated by using setwd(tempdir()) with a literal filename, or >>> writing to tempfile() is worth it. >> Thank you, Duncan. Well, setwd(tempdir()) should be made local to the >> examples if used at all, as the user may not expect to have the working >> directory changed. > > Yes, I agree. > > Duncan Murdoch > > ______________________________________________ > R-package-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel ______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
