Есть ли разумный способ сделать что-то вроде docstrings в R?

Это не просто вопрос стиля кодирования. Если вы знаете python (и я думаю, что у Ruby есть что-то подобное), вы можете иметь docstring в функции, чтобы вы могли легко получить эту строку, выпустив команду "help". например:.

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, вы можете получить полный текст определенного фрагмента кода, чтобы вы могли видеть комментарии (в том числе и в начале функции), но это может быть много прокрутки и визуальной фильтрации. Есть ли лучший способ?

Ответ 1

Недавно я написал пакет для выполнения этой задачи. Пакет 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")

Ответ 2

Вы можете добавить любые attributes вам понравятся объекты R, включая функцию. Так что что-то вроде

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"

Ответ 3

Сортировка - посмотрите roxygen2 пакет на CRAN (.. Вы пишете декларативный заголовок, и между прочим, страница помощи создается для вас, когда вы "roxygen-ize" из ваших источников.

Возможно, это не самый простой пакет, см. здесь в разделе SO для вопросов, относящихся к нему, а также его список рассылки. Но это, вероятно, самое близкое совпадение.

Ответ 4

RStudio позволяет легко создавать документацию. Подробнее см. их документацию.

Ответ 5

Новая система эталонного класса имеет нечто похожее на docstrings для документирования методов класса. Вот пример:

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

Ответ 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)

Вышеописанное показывает, что депаратизация действительно отменяет и отличается от того, что вы печатали в подсказке REPL, если вы набрали docstr: кавычки были изменены на двойные кавычки (по умолчанию), открытие фигурной скобки перемещается во вторую строку, и пустые строки (включая комментарии) удаляются. Это очень помогает, если вы хотите создать надежную функцию. Было бы тривиально искать, например, открытие и закрытие котировок вниз по первой строке, которая не начинается с цитаты.

Другой способ сделать это - получить список объектов вызова, которые составляют список тела с помощью body(docstr). Строка будет находиться в body(docstr)[[2]]. Я должен признать, что я немного из глубины здесь, так как я не совсем понимаю возвращаемое значение body и не знаю, где найти документацию! В частности, обратите внимание, что body(docstr)[2] возвращает объект типа и режим "вызов".

Этот последний подход кажется намного более LISPy. Мне бы хотелось услышать другие мысли по общей идее или указатели на реальные справочные материалы для этого языка!