0

I have taught a class in which I have had students use a package I have written. Now that the class is ending, I'd like to provide them the code for each of those functions inline with the documentation for the functions. Is there a global flag I can set to accomplish this? A code hack of some kind?

russellpierce
  • 4,583
  • 2
  • 32
  • 44
  • So you want the function code to show up in the help files for the code itself? Why? – Dason Mar 03 '13 at 16:10
  • 1
    this sounds more like "literate programming" than "reproducible research": http://rpubs.com/bbolker/3153 – Ben Bolker Mar 03 '13 at 16:18
  • @Dason: Yes, that is what I would like. Knowing my users, I think that they will find it easier to locate the scripts they want in a PDF than in a bunch of scattered ROxygen marked up scripts or even a single ROxygen marked up script. – russellpierce Mar 03 '13 at 16:31
  • @BenBolker: Yes it is a literate programming goal. I see the link on your page for http://stackoverflow.com/questions/2545136/is-literate-programming-dead. However the consensus seemed to be that it isn't dead. However, I guess I see the distinction that perhaps ROxygen wasn't designed for 'literate programming' per se. I know it isn't a typical usage case. My hope was that, since it is a similar usage case, it would be possible to coax ROxygen into providing the desired result. – russellpierce Mar 03 '13 at 16:35
  • Reading further it seems like if I had more foresight I would have just written everything in Sweave to begin with. Oddly enough, that is how I started off documenting my functions, but I switched to ROxygen when I decided to start putting them into a package... at the time I thought it was an improvement. – russellpierce Mar 03 '13 at 16:37
  • How do you expect the user to use this exactly? I'm having trouble seeing what the problem is with looking at the help file for a function and if you want to look at the code then type the name of the function in the interpreter. – Dason Mar 03 '13 at 16:37
  • @Dason: Having the function in the help file presupposes that there was a valid package to load that provided the help file. I am trying to shore up the future against a case where I might not have kept the package up-to-date with whatever bleeding edge version of R is out this month. True, they could load the PDF, search the PDF, load the scripts, search the scripts in order to get what they want, and copy and paste it into their script... or in my usage case they could just load the PDF, search, and copy/paste. – russellpierce Mar 03 '13 at 16:44

2 Answers2

1

You could pre-process your R files with the brew package, e.g.

File 'foo-tmp.r'

##' a function that doesn't do much 
##'
##' @title foo
##' @param x 
##' @param y 
##' @param z 
##' @return error message
##' @author Baptiste 
##' @examples
##' dontrun{
#<%= cat(paste0("##'", getSrcref(foo), "\n")) %> ##' }
foo <- function(x,  y,  z){
    rnorm(10) == 1
    # inline comment
    .NotYetImplemented()
    " other stuff"
    return(FALSE)
  }

Then process the file to generate foo.r

source("foo-tmp.r") # to know what the function is
brew("foo-tmp.r", "foo.r")

with resulting output:

##' a function that doesn't do much 
##'
##' @title foo
##' @param x 
##' @param y 
##' @param z 
##' @return error message
##' @author Baptiste 
##' @examples
##' dontrun{
###'function(x,  y,  z){
 ##'    rnorm(10) == 1
 ##'    # inline comment
 ##'    .NotYetImplemented()
 ##'    " other stuff"
 ##'    return(FALSE)
 ##'  }
 ##' }
foo <- function(x,  y,  z){
    rnorm(10) == 1
    .NotYetImplemented()
    " other stuff"
    return(FALSE)
  }
baptiste
  • 75,767
  • 19
  • 198
  • 294
  • in fact, you don't really need the two files, brew() probably doesn't do anything to a normal R file so you can happily overwrite without loss. – baptiste Mar 04 '13 at 00:27
  • But overwriting the file itself might lead to a situation where the function and the documentation are out of date. Then again if one is making this documentation and then never modifying the function again it doesn't matter too much... – Dason Mar 04 '13 at 01:48
  • This solution is far better than nothing but still not quite as parsimonious as I was hoping for. Is there a way to maybe use template tags to achieve the desired result without changing the code for each and every function that is to be documented? – russellpierce Mar 04 '13 at 02:49
0

See this related question. There is no global flag or solution. @baptiste's is as good as it gets. Answer set to community wiki in case this state of affairs changes.

Community
  • 1
  • 1
russellpierce
  • 4,583
  • 2
  • 32
  • 44