Как правильно документировать методы S4 с использованием Roxygen2
Я видел некоторые обсуждения в таких и других местах, касающихся того, как это должно быть или будет сделано в будущих версиях Roxygen2. Тем не менее, я застрял. Как мне пойти в документирование общих данных S4, а также его методы, используя ROXYGEN2? Рабочий пример для совершенно новых общих / методов, а также пример расширения базы S4 Generic будет невероятно полезным. Я не хочу делать отдельную (в основном) избыточную документацию для каждого метода S4 того же универсального значения.
СЛУЧАЯ ДИНДИНГ: Я отслеживал полезный пример для метода «Экстракт». Тем не менее, кажется устаревшим и неполным для моего вопроса. Он использует тег @SLOT в классной документации, которая не является (больше не?) Поддерживается. Он показывает только расширение метода сердечника S4 «[», а не полный пример ROXYGON, включая документацию общих данных S4.
Как правильно документировать 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. Однако до сих пор я заметил, что мои расширения основного метода «шоу» не имеют связанной ошибки, даже если они были задокументированы точно так же, как остальные. Вот пример полной документации ROXYGON, которую я включал над одним из методов 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 с ROXYGON2?
Есть ли хороший пример доступны где-то, что показывает полную информацию?
Что Может быть причиной, и решение, к предупреждению, что документация для большинства методов S4 отсутствует (даже если методы с «отсутствующей» документацией на самом деле имели свой документ, проанализированные ROXYGEN2, и полученные файлы RD, по крайней мере, достаточно хороши для работы в Пакет после
R CMD Build MyPKGName)?