如何编写 R 参考类的文档？

Question

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

如果我编写一个带有\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基本无事可查。由于我对此不满意，所以现在向社区询问当前的常规做法。

另外，该方法不被识别为代码对象，因此我需要相关文档。

- mariotomo

---

我不知道参考类是否也是如此，但对于S3类，您可以使用\alias来解决同样的问题。 - Andrie

很遗憾，使用块的工作方式并非如此。您是否阅读了有关内置引用类文档的帮助？ - hadley

@hadley：我以为我已经做了，但显然我错过了\S4method项的东西。你指的是哪个文档来描述它？ - mariotomo

在 "?ReferenceClasses" 中搜索帮助。 - hadley

是的，我已经这样做了，但是在那个页面中没有出现字符串S4method。（我正在使用R版本2.13.0（2011-04-13）） - mariotomo

Answer 1

如果我理解正确，参考类方法是S4方法，因此文档化S4类和方法适用。

为了使这个答案更加自包含，下面是我在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 类，而没有指定其方法：所有方法都会自动导出。

- mariotomo

Answer 2

我不知道这是否是正确的做法，但我所做的是创建一个方法部分，然后将方法文档放在内部的描述中。

- geoffjentry

---

好的，但更准确地说：在\usage部分内，我可以添加\S4method条目。 我记录每个S4method需要添加一个\alias条目。\alias中的条目不需要参数列表。 - mariotomo

如果我理解正确的话，那么你是对的。对于一个名为“foo”的方法，我倾向于为“foo”和“foo.class-method”创建别名，其中foo是方法的名称，class是类的名称。再次强调，我不能说这是正确的方法，只是我自己的做法。 - geoffjentry

Jeoff，检查一下我的另一个答案，它是否与你所做的相匹配？ - mariotomo

有没有将方法定义拆分到不同文件中的方法？就像initializr.R或populate.R一样？ - Matt Bannert