Документирование внутренней вспомогательной функции с использованием `roxygen2` - PullRequest
0 голосов
/ 04 января 2019

Я новичок в создании собственных пакетов и использую roxygen2.

Я создаю пакет с множеством внутренних вспомогательных функций, и мне было интересно, нужно ли мне документировать их все. Я понимаю важность документации, но некоторые функции довольно просты и просто обернуты вокруг других функций для удобства. Я выполнил базовый поиск в Интернете, но, похоже, не смог найти окончательного ответа.

Любая помощь приветствуется.

1 Ответ

0 голосов
/ 04 января 2019

Это зависит от того, что вы подразумеваете под «должен». Одно из объяснений: «Должен ли я документировать эти функции для прохождения проверок?» Ответ на этот вопрос - нет. Пока функция не экспортируется из пакета, R CMD check не потребует ее документирования.

Другое толкование: «Нужно ли документировать это, чтобы помочь себе в сохранении этого пакета?» На этот вопрос сложнее ответить. Некоторые функции настолько очевидны, что им не нужна никакая документация, кроме их имени, например, print метод без дополнительных аргументов, кроме аргументов универсального.

Другие функции не так очевидны или имеют аргументы, значение которых не очевидно. Это хорошая идея, чтобы документировать их, если вы планируете поддерживать свой пакет в течение длительного времени, потому что вы можете забыть детали между этим моментом и всякий раз, когда возникает проблема. А если вы выпускаете свой пакет для других, вам следует планировать долгосрочное обслуживание, потому что, если оно будет полезным, люди будут его использовать.

...