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

Question

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

Спасибо,

Hamy

Answer 1

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

Проверьте http://cran.r-project.org/doc/manuals/R-exts.html

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

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

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

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

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

Answer 3

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

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