对于使用roxygen(2)记录类,指定标题和描述/细节似乎与函数,方法,数据等相同.但是,插槽和继承是它们自己的动物类型.在roxygen2中记录S4类的最佳实践 - 当前或计划的最佳实践是什么？
尽职调查:
我@slot在早期的roxygen描述中发现了一个标签.
2008 R-forge邮件列表帖
似乎表明这已经死了,并且没有对@slotroxygen的支持:
roxygen2是真的吗？前面提到的帖子建议用户应该使用LaTeX标记创建自己的逐项列表.例如,扩展"character"该类的新S4类将被编码并记录如下:
#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' \describe{
#' \item{myslot1}{A logical keeping track of something.}
#'
#' \item{myslot2}{An integer specifying something else.}
#'
#' \item{myslot3}{A data.frame holding some data.}
#' }
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @exportClass mynewclass
setClass("mynewclass",
representation(myslot1="logical",
myslot2="integer",
myslot3="data.frame"), …我有一个R使用的包roxygen2.它有一些C代码/src,我刚开始使用Doxygen.有没有办法组合文档,或集成编译与roxygen2？在哪里放置C代码文档的"最佳实践" ？
谷歌搜索roxygen2和doxygen主要导致roxygen类似于doxygen结果.我找到了一些包含Doxyfiles的软件包,但没有一致的组织.例如,lme4 inst/doc/Doxyfile输出到源目录doxygen外部的文件夹lme4.在Matrix的根目录中还有一个Doxyfile(但在以前的版本中是这样的inst.此文档也导出到包目录之外.
是否有任何理由不在C包中包含文档,或者为什么Doxygen在R包中很少使用,尽管广泛使用C？
更新:查看相关的roxygen2功能请求
我现在正在编写一个地理编码功能,它依赖于Bing Maps Key.显然我宁愿不发布我的,并且没有一个例子就失败了.
如何包含一个示例供用户手动运行,但没有在执行期间执行R CMD check？
是否有一些机制可以转换roxygen看到的评论,最好是在进行roxygen-> rd转换之前？
例如,假设我有:
#' My function. Does stuff with numbers.
#'
#' This takes an input `x` and does something with it.
#' @param x a number.
myFunction <- function (x) {
}
现在,假设我想在roxygen解析之前对注释进行一些转换,例如用反引号替换所有实例\code{}.即:
preprocess <- function (txt) {
gsub('`([^ ]+)`', '\\\\code{\\1}', txt)
}
# cat(preprocess('Takes an input `x` and does something with it'.))
# Takes an input \code{x} and does something with it.
我可以preprocess以某种方式进入roxygen,以便它会在之前(或者在这种情况下工作之后)在doclet上运行它吗？roxygen会生成它的文档吗？
我不想在我的.r文件中进行永久性的查找替换.正如你可能从我的例子中猜到的那样,我的目标是在我的roxygen评论中提供一些基本的降价支持,因此希望保留我的.r文件以保持可读性(并以\code{..}编程方式插入内容).
如果我只是写我自己的版本roxygenise,运行preprocess …
我不知道发生了什么,一切都很好但突然间我开始在文档中出现此错误消息:
fetch(key)出错:lazy-load database'...... descopl.rdb'已损坏
我删除了几乎所有的代码并再次构建然后发布到Github,但是当我使用其他笔记本电脑下载软件包时,正在下载和加载软件包但我无法调用任何函数,并且文档说明了该错误.
我不知道是什么导致了这个问题,我使用roxygen来生成文档.
如何避免Rd文件名冲突
roxygenize()包roxygen2生成实际的Rd文件？roxygen2当通用及其方法分散在各个包中时,我不确定这是一个问题还是一个常见问题(如果遵循模块化编程风格,恕我直言肯定是一个真实的用例场景).
处理这些情况的推荐方法是什么？
在包中 pkga
假设在包中pkga你定义了一个通用方法foo,并且你已经提供了相应的roxygen代码来roxygenize()获取生成Rd文件:
#' Test function
#'
#' Test function.
#'
#' @param ... Further arguments.
#' @author Janko Thyson \email{janko.thyson@@rappster.de}
#' @example inst/examples/foo.R
#' @docType methods
#' @rdname foo-methods
#' @export
setGeneric(
name="foo",
signature=c("x"),
def=function(
x,
...
) {
standardGeneric("xFoo")
}
)
当roxygenizing()您的包时,foo-methods.Rd在man子目录中创建一个调用的文件,该子目录充当可能为此泛型方法创建的所有方法的引用Rd文件.到现在为止还挺好.如果这个通用的所有方法也是你的包的一部分,一切都很好.例如,这个roxygen代码将确保foo-methods.Rd为以下ANY方法添加文档foo:
#' @param x …我想知道link当我尝试使用新包编写文档时,存在一种从其他包中运行的方法roxygen2.有点像\link{pck=PACKAGE_NAME, fun=FUNCTION_NAME}？
我已经在SO和其他地方看到了一些关于在未来版本的Roxygen2中应该如何或将要完成的讨论.但是,我被卡住了.我应该如何使用Roxygen2记录S4泛型及其方法？一个全新的通用/方法的工作示例,以及扩展基础S4通用的示例将非常有用.我不想为同一个泛型的每个S4方法制作单独的(大多数)冗余文档.
尽职调查:我已经找到了"提取"方法的有用示例.但是,对于我的问题,它似乎已经过时且不完整.它在类文档中使用@slot标记,但不支持(不再？).它仅显示了核心S4方法"["的扩展,而不是包含S4泛型文档的完整Roxygen示例.
如何正确记录S4"["和"[< - "方法使用roxygen？
如果我用标题,描述完全记录一个新的S4泛型@param @return @name @aliases
@docType @rdname,然后用相应的文档记录S4方法@name @aliases
@docType @rdname,我得到以下R CMD check警告:
* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
<< long list of apparently undocumented methods. E.g. generic 'plot' and siglist 'myClass1,ANY' >>
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.
它首先看起来好像我用这种方式用roxygen2记录的S4方法都没有实际工作.但是,到目前为止,我注意到我的核心方法"show"的扩展没有相关的错误,即使它们的记录方式与其他方法完全相同.以下是我在其中一个show方法中包含的完整roxygen文档的示例,它没有生成遗漏文档错误:
#' @name show
#' @aliases show,myClass2-method
#' @docType methods
#' @rdname show-methods
因此,我很茫然.如您所见,我已经包含了R包手册的S4文档部分中描述的S4方法的别名约定,即方法应该具有以下名称的别名(没有空格):
generic,signature_list-method.
不知何故,这并没有被完全理解 …
简短版本:我可以使用Normal包装模拟文件吗？statsroxygen
长版本:我正在开发一个软件包,并试图通过在一个标题下收集一些具有公共输入/参数的函数来使文档更具可读性,这将是对该组的通用引用.每个功能仍应独立地供最终用户使用.
我把文档作为灵感Normal,给出了许多与正态分布相关的方法,例如stats::dnorm().
当我搜索时,?dnorm我发现帮助部分的名称Normal即使Normal看起来不是导出的函数或对象.
我试过的是将以下内容放入funs.R:
##' @rdname funs
##' @name funs
##' @aliases sum1
##' @aliases prod1
##' @title Two functions
##' @param x X
##' @param y Y
##' @return sum1 returns x+y
##' \cr
##' prod1 returns x*y
##' @examples
##' sum1(3,4)
##' prod1(3,4)
##' @export
sum1 <- function(x,y) x+y
##' @export
##' @rdname funs
prod1 <- function(x,y) x*y
然后我继续 …
我已经阅读了Roxygen2 PDF以及这个网站,我对@method @ S3method @export和你如何使用它们来正确记录S3方法之间的区别感到迷茫.我
编写了以下示例进行讨论:1.我如何正确记录这些内容？
2.我如何模拟？print和其他通用函数的文档,这些函数显示所有特定于类的实现的用例(即方式？print显示'factor','table','function'的用法)
3.来自wiki页面:"所有导出的方法都需要@ S3method标记.它的格式与@method相同.这会导出方法,而不是函数 - 即泛型(myobject)将起作用,但generic.mymethod(myobject)不会."
我无法解释这一点.这似乎说如果标签指定不正确,函数/方法调用将无法正常工作？具体会打破什么？
MyHappyFunction = function( x , ... )
{
UseMethod( "MyHappyFunction" )
}
MyHappyFunction.lm = function( x , ... )
{
# do some magic
}