Как мне документировать класс R Reference?

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

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

Answer 2

если я правильно понял, методы эталонных классов являются методами 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 Iпросто укажите, что я экспортирую класс Logger, я не указываю его методы: все автоматически экспортируются.