Question

这不仅仅是一个编码风格的问题。如果您了解python（我认为Ruby也有类似的东西），您可以在函数中使用docstring，这样您就可以通过发出“help”命令轻松获取该字符串。 e.g：

def something(t=None):
    '''Do something, perhaps to t

    t : a thing
        You may not want to do this
    '''
    if t is not None:
        return t ** 2
    else:
        return 'Or maybe not'

然后help(something)返回以下内容：

Help on function something in module __main__:

something(t=None)
    Do something, perhaps to t

    t : a thing
        You may not want to do this

R中的工作方式，你可以获得定义的代码片段的全文，这样你就可以看到注释（包括函数开头的注释），但这可能是很多滚动和可视化过滤。还有更好的办法吗？

Answer 1

您可以向R对象添加任何attributes，包括函数。像

这样的东西

describe <- function(obj) attr(obj, "help")
foo <- function(t=NULL) ifelse(!is.null(t), t^2, "Or maybe not")
attr(foo, "help") <- "Here is the help message"

产生或多或少的期望输出

> foo(2)
[1] 4
> foo()
[1] "Or maybe not"
> describe(foo)
[1] "Here is the help message"

Answer 2

我最近写了一个包来做这个任务。 docstring包允许用户在他们记录的函数中将其文档编写为roxygen风格注释。例如，可以做

square <- function(x){
    #' Square a number

    return(x^2)
}

然后查看文档调用docstring函数

docstring(square)

或使用内置的?支持并执行

?square

注释可以是上面显示的单个块，也可以是完全roxygen样式，以利用提供的一些关键字

square <- function(x){

    #' Square a number
    #'
    #' Calculates the square of the input
    #'
    #' @param x the input to be squared

    return(x^2)
}

现在在CRAN上：https://cran.r-project.org/package=docstring所以您可以使用

进行安装

install.packages("docstring")

或者如果您想要最新的开发版本，可以从github安装：

library(devtools)
install_github("dasonk/docstring")

Answer 3

排序 - 查看CRAN上的roxygen2包（vignette here)。您编写一个声明性标题，除其他外，当您'roxygen-ize'时，会为您创建一个帮助页面你的消息来源。

它可能不是最容易使用的软件包，请参阅此处的SO以了解与其相关的问题以及邮件列表。但它可能是最接近的匹配。

Answer 4

RStudio可以帮助您轻松创建文档。有关详细信息，请参阅their documentation。

Answer 5

新的引用类系统与文档字符串非常相似，用于记录类的方法。这是一个例子：

Something <- setRefClass("Something",
                         methods=list(
                           something=function(t=NULL) {
                             "Do something, perhaps to t
    t : a thing
        You may not want to do this
"
                             if(!is.null(t))
                               t^2
                             else
                               "Or maybe not"
                           }
                           ))


a <- Something$new()
a$something(2)
a$something()

Something$help("something") ## to see help page

Answer 6

我有另一个想法，因为我终于围绕着“R是一个（非常糟糕的）LISP”的事实。具体来说，您可以使用deparse命令访问源代码（通常）。因此，这个函数将是定义自己的自定义源代码解析帮助函数的开始：

docstr <- function(my.fun) {
    # Comments are not retained
    # So, we can put extra stuff here we don't want
    # our docstr users to see
    'This is a docstring that will be printed with extra whitespace and quotes'
    orig.code.ish <- deparse(my.fun)

    print(orig.code.ish[3])
}

docstr(docstr)

上面说明了deparse确实是deparse，并且与你在REPL提示下打印的内容有所不同，如果输入docstr：引号改为（默认）双引号，打开花括号移动到第二行，删除空行（包括注释）。如果您想设计一个强大的功能，这实际上有很大帮助。例如，通过不以引号开头的第一行打开和关闭报价是微不足道的。

另一种方法是使用body(docstr)获取构成正文列表的调用对象列表。该字符串将在body(docstr)[[2]]中。我不得不承认我在这里有点不太深入，因为我不完全理解body的返回值，也不知道在哪里可以找到文档！特别要注意的是body(docstr)[2]返回一个类型和模式'call'的对象。

后一种方法似乎更加LISPy。我很乐意听到其他人关于这个概念的想法，或者指出实际的语言参考资料！

是否有一种明智的方法可以像R中的docstrings那样做？

6 个答案: