相关疑难解决方法(0)

实际问题

如何避免Rd文件名冲突

1. 一个S4通用及其方法(或多个)不必然全部在相同的包中定义(含有(部分的)自定义方法(一个或多个)软件包依赖于包含所述通用包)和
2. 使用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 …

我发现R文档很重要,但创建/维护也很费时.有没有人使用过Roxygen,如果有的话,它是否有助于维护R包？我过去使用过Doxygen,但那些项目没有R包所需的man结构.

你可以在这里找到小插图.

下面我发布了一个迷你示例,其中我想“[“为S4类的方法编写文档.有人知道如何正确记录"["使用roxygen和S4 的通用方法吗？
在建造后检查包装时我收到警告(见下文).

#' An S4 class that stores a string.
#' @slot a contains a string
#' @export
setClass("testClass", 
         representation(a="character"))

#' extract method for testClass
#'
#' @docType methods
#' @rdname extract-methods
setMethod("[", signature(x = "testClass", i = "ANY", j="ANY"),
         function (x, i, j, ..., drop){
             print("void function")
         }
)

包检查摘录:

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
  generic '[' and siglist 'testClass'
All user-level objects in a package (including S4 …

一个简单的例子是我创建了一个扩展名show,这是一个S4基本方法.我不希望通过show在我的包中重新记录来导致消除歧义,我还想通过添加别名来合并我的扩展show的文档到新类的文档myPkgSpClass中show,myPkgSpClass-method.

#' @export
#' @aliases show,myPkgSpClass-method
#' @rdname myPkgSpClass-class
setMethod("show", "myPkgSpClass", function(object){ show(NA) })

我遇到的问题是,这会在roxygen2构建文档期间导致严重警告,Rd files with duplicated alias 'show':因为show此包中有多个类扩展,并且roxygen2已自动将别名列表中的通用术语添加到所有相关*-class.Rd文件:

\alias{show}
\alias{show,myPkgSpClass-method}

但我认为我不想在任何实例中使用通用别名,因为它会强制需要show在我的包和基础之间消除歧义show.此问题也适用于从其他包扩展的其他S4方法show.

如果我将所有特定于类的方法标记到同一个.Rd文件中,那么警告就会消失,但是模糊性仍然存在,因为show别名仍会自动添加到该文档条目中.如果我手动\alias{show}从.Rd文件中删除,那么问题似乎已解决,在roxygen期间没有警告R CMD check pkgname.那么如何让Roxygen2不添加通用别名呢？

其他背景:

这是从前一个问题构建的特定问题,用于将S4扩展导出/记录到基本方法: 是否需要在R包中导出基本方法扩展？文档含义？

关于使用Roxygen2记录S4方法/类的以下问题,它更具体,而不是包含在内:

如何使用roxygen2正确记录S4方法

如何使用Roxygen2正确记录S4类插槽？

在你瞄准和射击之前

我知道这个问题与这篇文章密切相关.事实上,我遵循了各种答案中给出的建议,但仍然认为生成的帮助文件有点"尴尬"或至少看起来有点"捣碎",因此我的问题

实际问题

1. 在记录S4泛型及其各自的方法时,如何最终得到一个Rd文件结构,让用户可以清楚地区分各种方法,使得文档的哪一部分特别属于哪种方法？
2. 鉴于我提供了@alias标签,在尝试获取特定方法的帮助时,如何实际使用它们？有点像?foo-character-method而不只是打字?foo吗？
3. 最好不要在通用方法中更好地记录a)签名参数,因为每个方法肯定都包含相应的文档和b)返回值,因为这也取决于相应的方法？

现在,我觉得我最终得到的帮助文件似乎无法正确区分通用和各种方法 - 至少在视觉上是这样.

但也许我还没有完全得到这个;-).在这种情况下,任何指针都将非常感谢!

这是一个可重现的示例,它生成mypkg包含S4泛型和两种方法的包.我试图遵循这篇文章中给出的建议和编写R扩展

确保目录

sapply(c("src", "package"), dir.create, showWarnings=FALSE)

通用方法定义

gnrc.roxy <- c(
    "#' Doing Something Useful",
    "#'", 
    "#' Description here.",
    "#'", 
    "#' @param x A signature argument for method dispatch.",
    "#' @param y A signature argument for method dispatch.",
    "#' @param arg.1 A \\code{logical} scalar. If \\code{TRUE} (default)", 
    "#'      something happens; else not.",
    "#' @param …