[inlinedocs] new inline example ideas

[Keith Ponting]

An interesting idea. One or two ramifications:

1) One thing that I like about the current mechanism (examples in tests
subdir) is that when the examples are run by R CMD check they are
automatically cross-checked against  a reference output (assuming that
exists). We could maintain this by checking whether
tests/is.pseudoprime.Rout.save exists and if so write the example into
tests/is.pseudoprime.R - we might want to do a diff/confirm overwrite if
that file already exists!

2) I think (but am not sure) that there would not be a problem with the
compilation in R CMD build (which checks for visible bindings) as all
the objects used in the examples should have visible bindings - but
maybe calls to library might get complained about? Yes, they do - if you
put a library(grid) call after the return statement you get a warning
like: 
* checking for unstated dependencies in R code ... WARNING
'library' or 'require' calls not declared from:
  grid
See the information on DESCRIPTION files in the chapter 'Creating R
packages' of the 'Writing R Extensions' manual.

3) In memory images of the functions would include the example code,
which might be useful or a pain, but if the latter then the present
system would be fine.

4) We need to be a little careful how the ### value line gets picked up
- IIRC the current code looks for ### lines immediately preceding the
function final }

5) The help markup includes \dontrun (which need not be legal R code)
\dontshow and \donttest  - if we are doing a bit of parsing to extract
the examples then, based on the example given in Writing R extensions
which is:
          x <- runif(10)       # Shown and run.
          \dontrun{plot(x)}    # Only shown.
          \dontshow{log(x)}    # Only run.
We could do something like the following at the end of the function,
extending the ##<< markup to suck in everything including the following
code lines:

  return(result)
### A pseudo-random sample from the uniform distribution
  ##example<<
  x <- runif(10)
  ##dontrun<< ... some bit of non-R code to show in example ...
  ##continuing over several lines, but valid R code can be included:
  plot(x)
  ##dontshow<<
  log(x)
  ##end<<
  ## and this bit does not get into the examples (don't yet know why we
might want it, but always keep options open)
}

the idea is that that lot would generate:

  x <- runif(10)
  \dontrun{ .. some bit of non-R code to show in example ...
continuing over several lines, but valid R code can be included:
  plot(x)}
  \dontshow{log(x)}


The point about library calls could then be answered by using
##example<< library(grid)
We could even answer the uncertainty about overwriting in 1) above by
having ##test<< as an alternative - chunks introduced by that would be
copied into the relevant tests file, whereas chunks with ##example<<
would only end up in the examples section of the documentation.

Keith

Keith Ponting
Aurix Ltd, Malvern WR14 3SZ  UK


> -----Original Message-----
> From: inlinedocs-support-bounces at lists.r-forge.r-project.org
> [mailto:inlinedocs-support-bounces at lists.r-forge.r-project.org] On
> Behalf Of Toby Dylan Hocking
> Sent: 22 April 2010 13:40
> To: twutz at bgc-jena.mpg.de
> Cc: inlinedocs-support at r-forge.wu-wien.ac.at
> Subject: [inlinedocs] new inline example ideas
> 
> First let me say that I can see where you're coming from. It would be
> beneficial to write examples right next to the function. In fact, this
> is the point of the inlinedocs package. However, putting them in
> comments using ##examples<< is not a solution I would be willing to
use.
> How about the following solution, adapted from the fermat example
(just
> look at the last few lines):
> 
> is.pseudoprime <- function#Check an integer for pseudo-primality to an
> arbitrary precision.
> ### A number is pseudo-prime if it is probably prime, the basis of ###
> which is the probabalistic Fermat test; if it passes two such ###
tests,
> the chances are better than 3 out of 4 that \eqn{n} is ### prime.
> ##references<< Abelson, Hal; Jerry Sussman, and Julie ##Sussman.
> Structure and Interpretation of Computer ##Programs. Cambridge: MIT
> Press, 1984.
> (n, ##<< the integer to test for pseudoprimality.
>  times ##<< the number of Fermat tests to perform ){
>   result <- if(times==0)TRUE
>   ##seealso<< \code{\link{fermat.test}}
>   else if(fermat.test(n)) is.pseudoprime(n,times-1)
>   else FALSE
>   return(result)
> ### Whether the number is pseudoprime
>   is.pseudoprime(13,4)
> }
> 
> here we have a return() line explicitly in the function definition, so
> the code after it will never be executed when you actually use
> is.pseudoprime in your package. However, we will be able to parse the
> lines after it to use for examples. Kind of tricky, huh? I just got
this
> idea and I like it!
> 
> advantages:
> - example code is not commented, so easily testable and correctly
> highlighted
> - example code is right next to the corresponding function
> 
> disadvantages:
> - need to use explicit return
> 
> any other ideas?
> _______________________________________________
> Inlinedocs-support mailing list
> Inlinedocs-support at lists.r-forge.r-project.org
>
https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/inlinedocs-
> support