Есть ли разумный способ сделать что-то вроде 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. Мне бы хотелось услышать другие мысли по общей идее или указатели на реальные справочные материалы для этого языка!