对于包含 S4 类的包，推荐的包构建工作流程是什么? [英] What's the recommended package build workflow with packages that contain S4 classes?

问题描述

可能的重复:
如何使用 Roxygen2 正确记录 S4 类插槽

我想使用 R Studio 和 roxygen2 构建一个包含 S4 类 的包.当我在包中引入几个 S4 类 时，我已经使用 roxygen2 语法记录了我的所有函数.

I would like to build a package that contains S4 classes using R Studio and roxygen2. I had already documented all my functions using roxygen2 syntax when I introduced a couple of S4 classes to my package.

现在我意识到没有现成的@slot"功能.所以我想知道如何让我的所有文档都适用于其他函数，并像 这个线程?

Now I realized that there's no '@slot' functionality out-of-the-box. So I wonder how can I keep all my documentation work for the other functions and document the S4 classes manually like suggested in this thread?

或者换句话说，您会推荐哪种工作流程来构建包含旧式函数和 S4 类 的包?

Or in other words which workflow would you recommend to built a package that contains both old school functions and S4 classes?

您是否建议将 R Studio 构建的工具配置为不创建 .Rd 文件.roxygenize 手动然后添加信息?这仍然会导致覆盖手动生成的类的 .Rd 文件......

Would you recommend to configure R Studio built tools not to create .Rd files. roxygenize manually and then add the info afterwards? Still this would lead to overwriting the manually generated .Rd files of the classes...

推荐答案

roxygen 和 S4 类的一般信息

roxygen 的第一个版本有一个 @slot 标签，但该版本不再维护以支持 roxygen2.所以建议不要使用那个旧版本.

General info on roxygen and S4 classes

The first version of roxygen had an @slot tag, but that version isn't maintained any more in favor of roxygen2. So it's advised against to use that old version.

就目前而言，roxygen2 并没有真正支持 S4 类.Hadley 正在努力在 roxygen3 (https://github.com/哈德利/roxygen3).如果您想尝试一下并感到勇敢:从 github 安装 roxygen3 并尝试开发版本.请注意，此版本最终会合并到 roxygen2 中，因此问题会及时解决.

As for now, roxygen2 doesn't have real support for S4 classes. Hadley is working hard to make that happen in roxygen3 (https://github.com/hadley/roxygen3). In case you want to give it a shot and feel brave: install roxygen3 from github and try the development version. Note that this version eventually will be incoorporated into roxygen2, so in time the problem will solve itself.

我个人总是觉得将使用 roxygen 和手动编写的 .Rd 文件结合起来是个坏主意.但如果必须，您可以使用参数 roxygen.dir 将 roxygen 的输出发送到不同的目录.这样你就可以将你想要的任何东西复制回包目录，而不会覆盖手动写入的文件.

I personally always find it a bad idea to combine using roxygen and manually written .Rd files. But if you must, you can send the output of roxygen to a different directory using the argument roxygen.dir. This way you can copy whatever you want back into the package directory without overwriting the manually written files.

roxygenise("./mypackage", roxygen.dir="./myroxygendir")

我要做的就是使用 roxygen2 为您的类编写 Rd 文件，如您链接到的线程中所述.您不必像您认为的那样出于某种未知原因手动添加它们.您只需像往常一样使用 #' 来指示 Rd 块，并使用您链接到的线程中给出的任何内容.如果你想让插槽成为一个单独的部分，你可以使用 @section 标签来做到这一点，就像下面的例子一样.

What I would do, is simply use roxygen2 to write the Rd files for your classes as explained in the thread you link to. You don't have to add them manually like you believe for some unknown reason. You just use the #' to indicate the Rd block like always, and use whatever is given in the thread you link to. If you want to make the slots a separate section, you can do that using the @section tag like in the example below.

目前使用 roxygen2 添加插槽的示例:

An example of how to add Slots for the moment using roxygen2 :

#' The MY class
#'
#' This class blabla yadayada
#'
#'@section Slots:
#'  \describe{
#'    \item{\code{aslot}:}{Object of class \code{"numeric"}, containing 
#'whatever and a bit more}
#'    \item{\code{anotherslot}:}{Object of class \code{"character"}, containing
#' strings.}
#'  }
#'
#' @note Yes, you can add notes
#' @name MY 
#' @rdname MY
#' @aliases MY-class
#' @exportClass MY
#' @author Joris Meys
setClass("MY",
         representation=representation(aslot="numeric",
                                       anotherslot="character"
                                       )

这篇关于对于包含 S4 类的包，推荐的包构建工作流程是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！