R中的函数注释约定

Posted

技术标签:

【中文标题】R中的函数注释约定【英文标题】:Function commenting conventions in R 【发布时间】:2011-09-13 13:15:05 【问题描述】:

我是 R 的新手,我一直在脚本文件中定义一些我自己的函数。我打算让其他人稍后重新使用它们,我找不到任何关于 R 函数注释约定的指南。我有什么办法让help("my_function_name") 显示一些帮助吗?如果没有,我是否只是将函数记录在脚本文件中,以便有人必须打印出(或打开脚本的源代码)才能看到 cmets?

谢谢,

哈米

【问题讨论】:

【参考方案1】:

在 2019 年 12 月更新这个问题,因为 R 宇宙自 2011 年最初编写时发生了变化

我现在推荐的资源是http://r-pkgs.had.co.nz/

原始答案(链接大多已过时)

记录您的函数并使其他人可以访问它们的规范方法是制作一个包。为了让您的包通过构建检查,您必须为每个函数/数据集提供足够详细的帮助文件。

查看http://cran.r-project.org/doc/manuals/R-exts.html#Creating-R-packages

Rob J Hyndman 的这篇博文非常有用,也是我最容易理解的博文之一:http://robjhyndman.com/researchtips/building-r-packages-for-windows/

我最近开始使用 roxygen 来协助制作和编译软件包:http://roxygen.org/

有很多很好的资源和人员可以在您有问题时提供帮助!

【讨论】:

Rob J Hyndman 博客文章的链接已损坏。或者,现在可以在 here 找到 pdf。 第二个和第三个url是404 @Borealis - 我添加了一个截至 2019 年准确的新参考资料......令人印象深刻的是,这个问题在近十年后仍然受到关注。【参考方案2】:

您可以研究的另一个(和较低键)替代方法是 comment()attr() 函数,用于向函数添加一些元数据。这是一个简单而愚蠢的例子:

FOO <- function(x,y) 
 x + y 


attr(FOO, "comment") <- "FOO performs simple addition"

#This can be arbitrary. "comment" is special. see ?comment for details.
attr(FOO, "help") <- "FOO expects two numbers, and it will add them together"

然后您可以使用attributes() 查看与FOO 相关的所有内容:

> attributes(FOO)
$source
[1] "function(x,y) " " x + y "         ""              

$comment
[1] "FOO performs simple addition"

$help
[1] "FOO expects two numbers, and it will add them together"

或提取特定部分:

> attr(FOO, "help")
[1] "FOO expects two numbers, and it will add them together"
attr(FOO, "comment")
[1] "FOO performs simple addition"

在评论的情况下,使用comment()

> comment(FOO)
[1] "FOO performs simple addition"

从长远来看,编写自己的包几乎肯定是值得的开销和时间投资,但如果由于某种原因在短期内不切实际 - 这是另一种选择。

【讨论】:

+1 我一直都在这样做,尤其是保存的工作空间和功能并不过分复杂但您想快速了解“它们做了什么”。【参考方案3】:

您必须将函数放入一个包中(这使得移植函数非常容易)。不久前,我写了一个short post,其中包含一些相关文档的链接(我希望它们仍然有效),这些文档扩展了该主题。

您可以使用roxygen、inlinedocs“即时”生成帮助文件。

【讨论】:

那是氧气回声吗?回声?

以上是关于R中的函数注释约定的主要内容,如果未能解决你的问题,请参考以下文章

.NET // vs /// 注释约定

Irrlicht 引擎:代码注释约定?

微软跨平台ORM框架之EFCore — 约定与属性映射

ORM系列之二:EF 约定注释Fluent API

tableView 函数中的命名约定

PostgreSQL中的函数中是不是有命名参数的约定