rroxygenroxygen2

Roxygen2 - how to properly document S3 methods


I've read the Roxygen2 PDF and this site, and I'm lost on the difference between @method @S3method @export and how to use these to properly document S3 methods. I worked up the follow example for discussion:

  1. How would I properly document these?

  2. How do I emulate documentation of ?print and other generic functions that show the use cases for all class-specific implimentations (i.e. the way ?print shows usage for 'factor', 'table','function')

  3. From the wiki page: "All exported methods need the @S3method tag. It has the same format as @method. This exports the method, not the function - i.e. generic(myobject) will work, but generic.mymethod(myobject) will not."
    I can't interpret this. This seems to say that function/method calls won't work properly if the tags are improperly specified? What specifically will break?
    MyHappyFunction = function( x , ... )
    {
        UseMethod( "MyHappyFunction" )
    }
    
    MyHappyFunction.lm = function( x , ... )
    {
      # do some magic
    }

Solution

  • The @method tag generates \method entries in the \usage field in Rd files.

    The @S3method tag generates S3method() entries in the NAMESPACE file.

    The @export tag generates export() entries in the NAMESPACE file.

    Here is my example:

    #' A description of MyHappyFunction
    #'
    #' A details of MyHappyFunction
    #'
    #' @title MyHappyFunction: The my happy function
    #' @param x numeric number
    #' @param ... other arguments
    #' @examples
    #' a <- 1
    #' class(a) <- "lm"
    #' MyHappyFunction(a)
    #'
    #' @rdname MyHappyFunction
    #' @export MyHappyFunction
    MyHappyFunction <- function(x, ...){
      UseMethod("MyHappyFunction")
    }
    
    #' @return \code{NULL}
    #'
    #' @rdname MyHappyFunction
    #' @method MyHappyFunction lm
    #' @S3method MyHappyFunction lm
    MyHappyFunction.lm = function(x, ...) {
      # do some magic
    }
    
    #' @return \code{NULL}
    #'
    #' @rdname MyHappyFunction
    #' @method MyHappyFunction default
    #' @S3method MyHappyFunction default
    MyHappyFunction.default = function(x, ...) {
      # do some magic
    }
    

    enter image description here

    3 From the wiki page...

    I guess that it means "you do not write @S3method generic mymethod myobject."