Как правильно документировать метод S3 общего типа из другого пакета, используя Roxygen?

Я пишу пакет, который определяет новый класс, геодезист и метод print для этого, т.е. print.surveyor. Мой код работает отлично, и я использую roxygen для встроенной документации. Но R CMD check выдает предупреждение:

Функции/методы с использованием в объект документации 'print.surveyor' но не в коде: print

Я использовал следующие две страницы, написанные Хэдли, как вдохновение: Namespaces и Функции документирования, в которых указано, что правильный синтаксис @method function-name class

Итак, мой вопрос: каков правильный способ документирования метода print для моего нового класса с использованием Roxygen? И, более конкретно, как мне избавиться от предупреждения?

Вот мой код: (Прокомментированная документация указала на попытки исправить это, ни одно из которых не сработало.)

#' Prints surveyor object.
#' 
#' Prints surveyor object
#' 
## #' @usage print(x, ...)
## #' @aliases print print.surveyor
#' @param x surveyor object
#' @param ... ignored
#' @S3method print surveyor
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

И роксигенизированный выход, т.е. print.surveyor.Rd:

\name{print.surveyor}
\title{Prints surveyor object.}
\usage{print(x, ...)
#'}
\description{Prints surveyor object.}
\details{Prints surveyor object

#'}
\alias{print}
\alias{print.surveyor}
\arguments{\item{x}{surveyor object}
\item{...}{ignored}}

Ответы

Ответ 1

Как и для roxygen2 > 3.0.0., вам нужно только @export, потому что roxygen может понять, что print.surveyor - это метод S3. Это означает, что вам теперь нужно только

#' Prints surveyor object.
#' 
#' @param x surveyor object
#' @param ... ignored
#' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

Однако, в этом случае, поскольку документация не очень полезна, лучше было бы просто сделать:

#' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}

Ответ 2

Update

Как и в случае с roxygen2 > 3.0.0, пакет получил намного более умный способ понять все это для вас. Теперь вам просто нужен тег @export и roxygen что вы документируете и делаете подходящую вещь при записи NAMESPACE и т.д. во время преобразования.

Существуют исключения, в которых вам может понадобиться помощь roxygen. Пример , который использует Хэдли Уикхэм в своей книге R Packages all.equal.data.frame. В этом имени функции есть неопределенность относительно того, что является классом, и какова общая функция (all, all.equal или all.equal.data)?

В таких случаях вы можете помочь roxygen, явно проинформировав его об общем и классе/методе, например

@method all.equal data.frame

В первоначальном ответе ниже подробно объясняется более старое поведение, если вам нужно явно использовать @method.

Оригинальные

Функция должна быть документирована тегом @method:

#' @method print surveyor

При первоначальном чтении документ @hadley немного смущал меня, поскольку я не знаком с roxygen, но после нескольких чтений раздела я думаю, что понимаю, почему вам нужно @method.

Вы пишете полную документацию для метода print. @S3method связан с NAMESPACE и упорядочивает способ экспорта. @S3method не предназначен для документирования метода.

В разделе usage ваш Rd файл должен иметь следующее:

\method{print}{surveyor}(x, ...)

если это работает правильно, так как это правильный способ документировать методы S3 в файлах Rd.