Roxygen2 - 如何正确记录 S3 方法 [英] Roxygen2 - how to properly document S3 methods
问题描述
我已经阅读了 Roxygen2 PDF 以及这个 网站,我我对@method @S3method @export 之间的区别以及如何使用它们正确记录 S3 方法之间的区别感到迷茫.我整理了以下示例进行讨论:
1. 我如何正确记录这些?
2. 我如何模拟 ?print 和其他通用函数的文档,这些函数显示所有特定于类的实现的用例(即 ?print 显示因子"、表"、函数"的用法的方式)
3.来自维基页面:所有导出的方法都需要@S3method标签.它与@method具有相同的格式.这会导出方法,而不是函数——即generic(myobject)可以工作,但是generic.mymethod(myobject)不会."
我无法解释这一点.这似乎是说如果标签指定不当,函数/方法调用将无法正常工作?具体会破坏什么?
I've read the Roxygen2 PDF as well as this site and I'm lost about the difference between @method @S3method @export and how you 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
}
推荐答案
@method
标签在 Rd 文件的 \usage 字段中生成 \method 条目.
The @method
tag generates \method entries in the \usage field in Rd files.
@S3method
标记在 NAMESPACE 文件中生成 S3method() 条目.
The @S3method
tag generates S3method() entries in the NAMESPACE file.
@export
标记在 NAMESPACE 文件中生成 export() 条目.
The @export
tag generates export() entries in the NAMESPACE file.
这是我的例子:
#' 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
}
3 来自维基页面...
3 From the wiki page...
我猜它的意思是你不写@S3method generic mymethod myobject
."
I guess that it means "you do not write @S3method generic mymethod myobject
."
这篇关于Roxygen2 - 如何正确记录 S3 方法的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!