如何记录 R 参考类？

发布于 2024-11-25 08:25:03 字数 748 浏览 1 评论 0原文

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

如果我编写带有 \usage 块的 Rd 文件，如何避免出现 WARNING

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

我期望 \usage< /code> 块允许我编写如下内容：

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

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

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

Assignments in \usage in documentation object 'ClassName':

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

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

原文

how do I document the use of member functions of a reference class?

if I write a Rd file with a \usage block, how do I avoid the WARNING

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

I'd expect the \usage block to allow me write things like:

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

and then I'd document the parameters in the \arguments block.

If I do this, R CMD check complains with

Assignments in \usage in documentation object 'ClassName':

and does not recognize the methods as code objects I need document.

as of now, I am writing Rd files without the \usage block and writing the above code in the \examples block, but then I have no place to document arguments and this way the check has very little to check actually. Since I'm not satisfied with this, I'm now asking the community about the current common practice.

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

梨涡少年 2024-12-02 08:25:03

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

回复收藏 0 原文

抚笙 2024-12-02 08:25:03

如果我理解正确的话，参考类方法是 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类，但我没有指定它的方法：所有方法都会自动导出。

if I understood correctly, Reference Classes methods are S4 methods, so documenting S4 classes and methods applies.

to make this answer a bit more self contained, here is what I am doing in the case of the Logger class in the logging.oo package.

this is the code I wanted to document, with some omissis [...].

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

this is the corresponding content of the .Rd file(s):

\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}(...)

while in the NAMESPACE file I just indicate I'm exporting the Logger class, I don't specify its methods: all are automatically exported.

回复收藏 0 原文

~没有更多了~