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

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

20 голосов
/ 13 июня 2011

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

Ответы [ 3 ]

21 голосов
/ 13 июня 2011

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

Извлечение http://cran.r -project.org / doc / manual /R-exts.html # Создание-R-пакетов

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

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

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

15 голосов
/ 13 июня 2011

Другой (и нижний ключ) альтернативой, которую вы могли бы рассмотреть, являются функции 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"

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

7 голосов
/ 13 июня 2011

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

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

...