Skip to content

[R-pkg-devel] need some help to understand package build workflow

10 messages · Glenn Schultz, Hadley Wickham, Kevin Ushey +1 more

#
Hi All,

I have a package stable and working. ?Now, I am trying to consolidate some functions that share similar inputs. ?Example below. ?So, I branched on github and work with the branch but now when I run the R check in studio I get the following warning:

* checking Rd \usage sections ... WARNING
Documented arguments not in \usage in documentation object 'Effective.Measure':
? ?type?

Clearly type is documented. ?Perhaps this is an R studio/git hub issue. Travis tells me the build is broken. ?I am trying to build and work with the package within standards so I am not sure what happened. ? Maybe this is not a topic that belongs here but I can't find answers on the internet.

Glenn

#' A function to compute effective duration and convexity
#'?
#' Calculates the effective duration and based on discount vector (zero coupon)
#' cashflow vector, and rate delta
#' @param Rate.Delta A numeric value the interest rate shift in basis points
#' @param cashflow A numeric vector of cashflow
#' @param discount.rates A numeric vector of the discount rates
#' @param time.period A numeric vector of the time period
#' @param type A character vector to specify either duration or convexity
#' @export
Effective.Measure <- function(Rate.Delta = numeric(),?
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?cashflow = vector(),?
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?discount.rates = vector(),?
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?time.period = vector(),
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?type = "character"){
??
? discount.rates.up = discount.rates + Rate.Delta
? discount.rates.dwn = discount.rates - Rate.Delta
? Price.NC = sum((1/((1+discount.rates)^time.period)) * cashflow)
? Price.UP = sum((1/((1+discount.rates.up)^time.period)) * cashflow)
? Price.DWN = sum((1/((1+discount.rates.dwn)^time.period)) * cashflow)
??
? switch(type,
? ? ? ? ?duration = ? (Price.UP - Price.DWN)/(2*Price.NC*Rate.Delta),
? ? ? ? ?convexity = ?(Price.UP + Price.DWN - (2*Price.NC))/(2*Price.NC*(Rate.Delta^2)))

}

setGeneric("Effective.Measure", function(Rate.Delta = numeric(),?
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? cashflow = vector(),?
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? discount.rates = vector(),?
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? time.period = vector())
{standardGeneric("Effective.Measure")})
#
On 30/07/2015 8:49 PM, Glenn Schultz wrote:
No, it's not clear that type is documented.  You're only showing us the
.R file, not the .Rd file that Roxygen (?) produced from it.

Duncan Murdoch
#
On 30/07/2015 9:14 PM, Duncan Murdoch wrote:
Discussion went private for a few emails, so to finish this thread here:

Turns out roxygen2 was generating a bad .Rd file, so this is a roxygen2 bug.

Duncan Murdoch
#
On Thursday, July 30, 2015, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:

            
Hadley
#
I've posted an MRE at https://github.com/klutometis/roxygen/issues/362.

The issue occurs when a function and an S4 generic have the same name;
I imagine this is fairly uncommon? Wouldn't the function be masked by
the S4 generic and effectively be invisible after the package was
loaded?
On Thu, Jul 30, 2015 at 7:53 PM, Hadley Wickham <h.wickham at gmail.com> wrote:
#
It seems arguable that this is actually a roxygen bug - the function
that's actually exported from the package does not have a type
argument.

Hadley
On Fri, Jul 31, 2015 at 12:53 AM, Kevin Ushey <kevinushey at gmail.com> wrote:

  
    
#
On 31/07/2015 7:11 AM, Hadley Wickham wrote:
The package fails R CMD check because of a bad .Rd file.  If a user had
written that file, it would be user error, but roxygen2 wrote it, so I'd
say it's pretty clearly a roxygen2 bug.

Duncan Murdoch
#
It would really help me if you'd explain a little bit more. I think
the essential problem is that the package has two definitions of f:

f <- function(x, y) {}
setGeneric(f, function(x) {})

Roxygen uses the second definition (because it's the last defined),
and expects the function to have one argument. R CMD check clearly
excepts it two have two arguments. It's not obvious to me which is
correct.

Hadley
#
I'm not sure if that's correct -- from what I see, in the generated Rd
documentation:

- The 'usage' is drawn from the S4 generic,
- The 'arguments' are drawn from the function.

I think R CMD check is correctly warning about that.
On Fri, Jul 31, 2015 at 2:56 PM, Hadley Wickham <h.wickham at gmail.com> wrote:
#
On 31/07/2015 6:14 PM, Kevin Ushey wrote:
I agree the warning is correct.

I'm not so sure it's actually a Roxygen2 bug, but I think it's that, or
a missing feature.  The user documented an argument that doesn't exist,
because the function is defined twice.  Since Roxygen uses position in
the file to match docs to functions, it could have complained that the
argument docs were in the wrong place (before the inactive definition),
or it could have complained that they were inconsistent with the
expected arg list.

Duncan