roxygen documentation doesn't generate `\method{}{}` calls in `\usage{}`

I converted an R package from .Rd to roxygen documentation, and am getting warnings from R CMD check I can't understand and resolve.

One file with this problem is ridge.R and the .Rd file created by devtools::document() is ridge.Rd.

The problem is that I'm defining several S3 methods for a ridge class, and these do not appear as \method{}{ridge}(arguments, ...) under \usage{} which declares the arguments for each method. Hence, the warning I get is:

  Documented arguments not in \usage in documentation object 'ridge':
    'X' 'formula' 'data' 'lambda' 'df' 'svd' 'x' 'object' 'digits'
  
  Functions with \usage entries need to have the appropriate \alias
  entries, and all their arguments documented.
  The \usage entries must correspond to syntactically valid R code.
  See chapter 'Writing R documentation files' in the 'Writing R
  Extensions' manual.

Some relevant parts of my [ridge.R(https://github.com/friendly/genridge/blob/roxygenize/R/ridge.R) file:

#' Ridge Regression Estimates
#' 
#' @name ridge
#' @aliases ridge ridge.default ridge.formula coef.ridge print.ridge vcov.ridge
#'
#' @description  
#' The function \code{ridge} fits linear models by ridge regression, returning
#' an object of class \code{ridge} designed to be used with the plotting
#' methods in this package.
#' 
#' @param y A numeric vector containing the response variable. NAs not allowed.
#' @param X A matrix of predictor variables. NA's not allowed. Should not
#'        include a column of 1's for the intercept
#' @param formula For the \code{formula} method, a two-sided formula
#' @param data For the \code{formula} method, data frame within which to
#'        evaluate the formula
#' @param lambda A scalar or vector of ridge constants. A value of 0
#'        corresponds to ordinary least squares.
#' @param df A scalar or vector of effective degrees of freedom corresponding
#'        to \code{lambda}
#' @param svd If \code{TRUE} the SVD of the centered and scaled \code{X} matrix
#'        is returned in the \code{ridge} object.
#' @param x,object An object of class \code{ridge}
#' @param \dots Other arguments, passed down to methods
#' @param digits For the \code{print} method, the number of digits to print.
#' 
#' @return A list with the following components: 

...
#' @export
ridge <- function(y, ...) {
    UseMethod("ridge")
}

#' @export 
ridge.formula <-
        function(formula, data, lambda=0, df, svd=TRUE, ...){
  ...
  }

#' @export 
ridge.default <-
        function(y, X, lambda=0, df, svd=TRUE, ...){
    ...
    }
  
...

In the .Rd file, I get:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ridge.R
\name{ridge}
\alias{ridge}
\alias{ridge.default}
\alias{ridge.formula}
\alias{coef.ridge}
\alias{print.ridge}
\alias{vcov.ridge}
\title{Ridge Regression Estimates}
\usage{
ridge(y, ...)
}
\arguments{
\item{y}{A numeric vector containing the response variable. NAs not allowed.}

\item{\dots}{Other arguments, passed down to methods}

\item{X}{A matrix of predictor variables. NA's not allowed. Should not
include a column of 1's for the intercept}

\item{formula}{For the \code{formula} method, a two-sided formula}

\item{data}{For the \code{formula} method, data frame within which to
evaluate the formula}
...

I would have expected that the usage{} section included the \method{}{} calls:

\usage{
ridge(y, ...)
}
\method{ridge}{default}(y, X, data, lambda=0, df, svd=TRUE, ...)
\method{ridge}{formula}(formula, data, lambda=0, df, svd=TRUE, ...)
}
 ...

I think the following is true:

The minimum you need to do with Roxygen to handle S3 methods is to add the #' @export directive, as you did. This will put the appropriate declaration in the NAMESPACE file, but won't add any documentation entry, because S3 methods often don't need to be documented.

If you do want them to be documented, you have two choices. You can add full Roxygen comments before the method definition, and Roxygen will generate a new Rd file for that method.

Alternatively, you can add a #' @rdname foo directive as well as the #' @export directive, and Roxygen will generate the appropriate markup in the \usage section of the Rd file.

One case where the method does need to be documented is if it uses arguments that aren't present in the generic (as most methods do), and where you want to document those arguments. As you saw, you can't document an argument that isn't mentioned in the \usage section, so you'll have to use one of the approaches above.