Я видел некоторые дискуссии в SO и других местах относительно того, как это должно быть или будет сделано в будущих версиях Roxygen2. Однако я застрял. Как мне следует документировать общий ролик S4, а также его методы, используя Roxygen2? Рабочий пример для новых родовых/методов, а также пример расширения базового S4-родового значения будет невероятно полезным. Я не хочу делать отдельную (в основном) избыточную документацию для каждого метода S4 того же родового.
Due dilligence: Я нашел полезный пример для метода "extract". Однако, по моему мнению, он является устаревшим и неполным. Он использует тег @slot в документации по классу, который не поддерживается (больше не поддерживается). Он показывает только расширение основного S4-метода "[", а не полный пример Roxygen, включая документацию по S4 generic.
Как правильно документировать S4 "[" и "[< -" методы с использованием roxygen?
Если я полностью документирую новый родовой файл S4 с заголовком, описанием @param @return @name @aliases
@docType @rdname
, а затем документирую метод S4 только с соответствующим @name @aliases
@docType @rdname
, я получаю следующее предупреждение R CMD check
:
* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
<< long list of apparently undocumented methods. E.g. generic 'plot' and siglist 'myClass1,ANY' >>
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.
Сначала он выглядел так, как будто ни один из моих S4-методов, описанных таким образом с roxygen2, фактически не работал. Однако до сих пор я заметил, что мои расширения основного метода "show" не имеют связанной ошибки, хотя они были задокументированы точно так же, как и остальные. Ниже приведен пример полной документации по roxygen, включенной выше одного из методов show, который НЕ генерировал ошибку с отсутствующей документацией:
#' @name show
#' @aliases show,myClass2-method
#' @docType methods
#' @rdname show-methods
Таким образом, я в недоумении. Как вы можете видеть, я включил соглашение для псевдонимов для методов S4, описанных в в разделе документации S4 руководства по пакетам R, а именно: методы должны иметь псевдоним со следующим именем (без пробела):
generic,signature_list-method.
Каким-то образом это не полностью понимается R CMD check
.
Наконец, после создания документации, используя:
library("devtools")
library("roxygen2")
document("mypkgname")
check_doc("mypkgname")
и создавая пакет, я получаю действующую документацию. Любые заголовки из специальной документации метода заканчиваются в поле "Описание", что довольно неловко. Поэтому roxygen2 явно что-то сделал с каждой документацией метода и находится на правильном пути. Однако этого недостаточно, чтобы избежать большого и тревожного предупреждения от
> R CMD check mypkgname
Я просмотрел файлы Rd, но я знаю еще меньше о них, чтобы быстро понять, в чем проблема, и я все равно хочу знать решение roxygen2, чтобы мне не пришлось манипулировать файлами Rd непосредственно после каждого пересмотр документации.
Итак, это вопрос с несколькими вопросами:
-
Каков нынешний рекомендуемый подход как для документации по S4, так и для S4 с помощью roxygen2?
-
Есть ли где-нибудь хороший пример, который показывает полную информацию?
-
Какова может быть причина и решение для предупреждения о том, что документация для большинства методов S4 отсутствует (даже если методы с "отсутствующей" документацией фактически имели свой документ, обработанный roxygen2, и полученные Rd файлы по крайней мере, достаточно, чтобы работать в пакете после
R CMD build mypkgname
)?