Как мне документировать справочный класс R?

Question

Как мне документировать использование функций-членов ссылочного класса?

если я напишу Rd файл с \usage блок, как мне избежать WARNING

Functions/methods with usage in documentation object 'XmlDoc' but not in code:
  $ new

Я бы ожидал \usage блок, чтобы позволить мне писать такие вещи, как:

obj <- ClassName$new(par1, par2, ...)
obj$method1(oth1, ...)

а затем я задокументирую параметры в \arguments блок.

Если я сделаю это, R CMD check жалуется с

Assignments in \usage in documentation object 'ClassName':

и не распознает методы как объекты кода, мне нужен документ.

на данный момент я пишу Rd файлы без \usage заблокировать и записать вышеуказанный код в \examples блок, но тогда у меня нет места для документирования аргументов и таким образом check есть очень мало, чтобы проверить на самом деле. Поскольку меня это не устраивает, я сейчас спрашиваю сообщество о текущей общей практике.

Answer 1

Я не знаю, правильный ли это путь, но я создал раздел " Методы ", а затем поместил документацию по методу во внутреннее описание.

Answer 2

Если я правильно понял, методы Reference Classes - это методы S4, поэтому применяется документирование классов и методов S4.

чтобы сделать этот ответ немного более самодостаточным, вот что я делаю в случае Logger класс в logging.oo пакет.

это код, который я хотел документировать, с некоторым упущением [...].

Logger <- setRefClass("Logger",
                      fields=list(name = "character"),
                      methods=list(
                        setLevel = function(newLevel) { [...] },
                        getLevel = function() { [...] },
                        addHandler = function(...) { [...] },

это соответствующее содержимое файла.Rd:

\alias{\S4method{new}{Logger}}
\alias{\S4method{setLevel}{Logger}}
\alias{\S4method{getLevel}{Logger}}
\alias{\S4method{addHandler}{Logger}}
[...]
\usage{
\S4method{new}{Logger}(name)
\S4method{setLevel}{Logger}(newLevel)
\S4method{getLevel}{Logger}()
\S4method{addHandler}{Logger}(...)

в то время как в файле NAMESPACE я просто указываю, что экспортирую класс Logger, я не указываю его методы: все они автоматически экспортируются.