如何记录 R 参考类？答案

【问题标题】：how do I document an R Reference Class?如何记录 R 参考类？
【发布时间】：2011-07-20 08:27:49
【问题描述】：

如何记录引用类的成员函数的使用？

如果我写一个带有\usage 块的Rd 文件，我该如何避免WARNING

Functions/methods with usage in documentation object 'XmlDoc' but not in code:
  $ new

我希望 \usage 块允许我编写如下内容：

obj <- ClassName$new(par1, par2, ...)
obj$method1(oth1, ...)

然后我会在 \arguments 块中记录参数。

如果我这样做，R CMD check 会抱怨

Assignments in \usage in documentation object 'ClassName':

并且不将方法识别为我需要文档的代码对象。

截至目前，我正在编写没有 \usage 块的 Rd 文件，并在 \examples 块中编写上述代码，但是我没有地方记录参数，这样check 非常实际上几乎没有检查。由于对此我不满意，我现在向社区询问当前的常见做法。

【问题讨论】：

我不知道引用类是否也是这种情况，但是 S3 类你会使用\alias 来解决同样的问题。
不幸的是，这不是使用块的工作方式。您是否阅读过有关内置参考类文档的帮助？
@hadley：我以为我有，但显然我错过了\S4method 项目。您参考了哪些描述它的文档？
在“?ReferenceClasses”中搜索帮助。
是的，我做到了，但该页面中没有出现字符串S4method。（我使用的是 R 版本 2.13.0 (2011-04-13)）

标签： r documentation rd reference-class

【解决方案1】：

我不知道这是否正确，但我所做的是有一个 Methods 部分，然后将方法文档放在内部 describe .

【讨论】：

好的，但更准确地说：在\usage 部分内，我可以添加\S4method 条目。对于我记录的每个 S4 方法，我需要添加一个 \alias 条目。 \alias 中的条目不需要参数列表。
如果我理解你是对的，那么你是对的。对于方法“foo”，我倾向于为“foo”和“foo.class-method”创建一个别名，其中 foo 是方法的名称，class 是类的名称。再说一次，我不能说这是正确的方法，我就是这样做的。
杰夫，检查我的其他答案，它是否符合您也在做的事情？
有没有办法在单独的文件中拆分方法定义。喜欢initializr.R 或populate.R？

【解决方案2】：

如果我理解正确，Reference Classes 方法是 S4 方法，所以documenting S4 classes and methods 适用。

为了让这个答案更加独立，下面是我在 logging.oo 包中的 Logger 类的情况下所做的事情。

这是我想要记录的代码，有一些遗漏 [...]。

Logger <- setRefClass("Logger",
                      fields=list(name = "character"),
                      methods=list(
                        setLevel = function(newLevel) { [...] },
                        getLevel = function() { [...] },
                        addHandler = function(...) { [...] },

这是 .Rd 文件的对应内容：

\alias{\S4method{new}{Logger}}
\alias{\S4method{setLevel}{Logger}}
\alias{\S4method{getLevel}{Logger}}
\alias{\S4method{addHandler}{Logger}}
[...]
\usage{
\S4method{new}{Logger}(name)
\S4method{setLevel}{Logger}(newLevel)
\S4method{getLevel}{Logger}()
\S4method{addHandler}{Logger}(...)

虽然在 NAMESPACE 文件中我只是指出我正在导出 Logger 类，但我没有指定它的方法：所有都是自动导出的。

【讨论】：