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.boshna...@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-boun...@r-project.org] On > Behalf Of Tomas Hudik > Sent: 18 December 2017 13:38 > To: r-package-devel@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@r-project.org mailing list https://stat.ethz.ch/mailman/ > listinfo/r-package-devel > [[alternative HTML version deleted]] ______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
