Соглашения о комментировании функций в R

Я новичок в R, и я определяю некоторые из своих собственных функций в файлах script. Я намереваюсь, чтобы другие повторно использовали их позже, и я не могу найти никаких руководств по соглашениям о комментировании функций R. Есть ли способ сделать help("my_function_name") помощь? Если нет, я просто документирую функцию в файле script, чтобы кто-то распечатывал (или открывал источник) script, чтобы увидеть комментарии?

Спасибо,

Hamy

Ответы

Ответ 1

Канонический способ документировать ваши функции и сделать их доступными для других - это сделать пакет. Чтобы пакет прошел проверку сборки, вам необходимо предоставить достаточно подробные файлы справки для каждой из ваших функций/наборов данных.

Отъезд http://cran.r-project.org/doc/manuals/R-exts.html#Creating-R-packages

Это сообщение в блоге от Роба Хиндмана было очень полезным и одним из самых простых для меня: http://robjhyndman.com/researchtips/building-r-packages-for-windows/

Я начал использовать roxygen, чтобы помочь в создании и компиляции пакетов в последнее время: http://roxygen.org/

Много хороших ресурсов и людей, чтобы помочь, когда у вас есть вопросы!

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

Затем вы можете увидеть все, связанное с FOO, используя attributes():

> 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"

В долгосрочной перспективе написание собственного пакета почти наверняка будет стоить накладных и временных инвестиций, но если по какой-то причине это не практично в краткосрочной перспективе - вот еще один вариант.

Ответ 3

Вам нужно будет поместить функции в пакет (что делает функцию портирования ДЕЙСТВИТЕЛЬНО легкой). Я написал короткое сообщение об этом некоторое время назад со ссылками (надеюсь, они все еще работают) на некоторые релевантные документы, которые расширяют тему.

Вы можете создавать файлы справки "на лету" с помощью roxygen, inlinedocs.