Generic should come before method

[krlmlr]

in the "Usage" section.

Often, the following pattern is used to document an S3 generic along with its methods:

#' Some
#'
#' Method.
#' @export
some_method <- function(x, ...) UseMethod("some_method")

#' @rdname some_method
#' @export
some_method.data.frame <- function(x, ...) {
  # Method implementation for data frames
}

Currently, they are shown in order of appearance, and collation or renaming files is necessary to make sure the generic appears first. (Also, \name{} and \alias{} seem wrong.)

library(roxygen2)
roc_proc_text(rd_roclet(), "
#' @rdname some_method
#' @export
some_method.data.frame <- function(x, ...) {
  # Method implementation for data frames
}

#' Some
#'
#' Method.
#' @export
some_method <- function(x, ...) UseMethod('some_method')
")
#> $some_method.Rd
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in Rtmp5qvmr0/file34342bfb9414
#> \name{some_method.data.frame}
#> \alias{some_method.data.frame}
#> \alias{some_method}
#> \title{Some}
#> \usage{
#> \method{some_method}{data.frame}(x, ...)
#> 
#> some_method(x, ...)
#> }
#> \description{
#> Method.
#> }

^{Created on 2019-05-19 by the reprex package (v0.2.1)}

[hadley]

The only way I can see to implement this would be to add a special @order tag, then add a new block ordering step that's executed after parsing in roc_proc_text() and roxygenise(). (It would a special tag because it wouldn't be processed by a roclet). I think the default order value would be Inf so that any order value would cause the block to bubble to the front.

[krlmlr]

Great! This will make @include obsolete in many cases.