R devel - Nov 2010 - Roxygen: @example tag does not work for me

Dear list,

 

somehow I can't get the Roxygen tag "@example" to work for me.

 

My "Roxygen-Header" of a script containing, say, a function looks like
this:

 

#' My header

#' 

#' My description

#' 

#' @param a Blabla.

#' @param b Blabla.

#' @return \code{TRUE}. 

#' @callGraphPrimitives

#' @references

#' \url{http://www.something.org /}

#' @author Janko Thyson \email{my.email@@something.com}

#' @example tests/foo.R

#' @seealso \code{\link{some.other.function}}

Foo <- function(a, b){cat("Doing nothing useful.")} 

 

I thought that @example would take the R code in "tests/foo.R" (this
file
also exists) and append it to the .Rd-file. However, there is no
\examples{...} section in my roxygen-processed .Rd-file after running
roxygenize(). It just seems as if @example is just neglected. Should I put
the file in another directory? 

 

The basic thing I'm trying to do is to have the "unit tests" for
my
functions organized in separate scripts and then plug in some of their
content as examples in the .Rd-files (this should be accomplished by using
in-source documentation ? la Roxygen ? thus something like "@example"
pointing to such a script file would be very neat). I'd definitely like to
get around to "manually" specifying examples via the other tag
"@examples"
as they will most likely lead to "out-of-sync" situations regarding
the unit
test files. Any ideas?

 

Thanks a lot!

Janko

Hi,

I think you could achieve this using the brew package. Define a
function that reads your external example file, and have brew insert
the resulting string in your script, which can then be processed by
roxygen.

I'm curious to hear other suggestions, but I doubt it could work
out-of-the-box like you intended.

HTH,

baptiste

On 4 November 2010 01:50, Janko Thyson <janko.thyson at ku-eichstaett.de>
wrote:
> Dear list,
>
>
>
> somehow I can't get the Roxygen tag "@example" to work for
me.
>
>
>
> My "Roxygen-Header" of a script containing, say, a function looks
like this:
>
>
>
> #' My header
>
> #'
>
> #' My description
>
> #'
>
> #' @param a Blabla.
>
> #' @param b Blabla.
>
> #' @return \code{TRUE}.
>
> #' @callGraphPrimitives
>
> #' @references
>
> #' \url{http://www.something.org /}
>
> #' @author Janko Thyson \email{my.email@@something.com}
>
> #' @example tests/foo.R
>
> #' @seealso \code{\link{some.other.function}}
>
> Foo <- function(a, b){cat("Doing nothing useful.")}
>
>
>
> I thought that @example would take the R code in "tests/foo.R"
(this file
> also exists) and append it to the .Rd-file. However, there is no
> \examples{...} section in my roxygen-processed .Rd-file after running
> roxygenize(). It just seems as if @example is just neglected. Should I put
> the file in another directory?
>
>
>
> The basic thing I'm trying to do is to have the "unit tests"
for my
> functions organized in separate scripts and then plug in some of their
> content as examples in the .Rd-files (this should be accomplished by using
> in-source documentation ? la Roxygen ? thus something like
"@example"
> pointing to such a script file would be very neat). I'd definitely like
to
> get around to "manually" specifying examples via the other tag
"@examples"
> as they will most likely lead to "out-of-sync" situations
regarding the unit
> test files. Any ideas?
>
>
>
> Thanks a lot!
>
> Janko
>
>
>
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>

> I thought that @example would take the R code in "tests/foo.R"
(this file
> also exists) and append it to the .Rd-file. However, there is no
> \examples{...} section in my roxygen-processed .Rd-file after running
> roxygenize(). It just seems as if @example is just neglected. Should I put
> the file in another directory?
I would suspect that the path would be relative to either man/ or R/ -
so you probably want ../tests/...

But including your unit tests as examples seems like a pretty odd
thing to do - they do serve rather different purposes.

Hadley

-- 
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/