Feature request: ability to specify order of params

[rossellhayes]

I'd like to be able to specify the order that arguments are documented when I document multiple functions with semi-overlapping arguments in the same .Rd file.

Motivating example

I have two functions documented in the same .Rd file:

#' Two functions
#' @param a First argument
#' @param b Second argument
#' @param c Third argument
#' @param ... Dots
#' @param z Last argument
f1 <- function(a, b, ..., z) {...}

#' @rdname f1
f2 <- function(b, c, ..., z) {...}

I'd like my arguments to be ordered a, b, c, ..., z in my documentation. If I document f1 before f2, I get an order of

\arguments{
\item{a}{First argument}

\item{b}{Second argument}

\item{...}{Dots}

\item{z}{Last argument}

\item{c}{Third argument}
}

If I flip the order of functions and document f2 before f1, I still get the wrong order:

#' Two functions
#' @param a First argument
#' @param b Second argument
#' @param c Third argument
#' @param ... Dots
#' @param z Last argument
f2 <- function(b, c, ..., z) {...}

#' @rdname f2
f1 <- function(a, b, ..., z) {...}

\arguments{
\item{b}{Second argument}

\item{c}{Third argument}

\item{...}{Dots}

\item{z}{Last argument}

\item{a}{First argument}
}

The only way I've found to avoid this problem is by including a dummy function that "uses" all the arguments from both functions.

#' Two functions
#' @param a First argument
#' @param b Second argument
#' @param c Third argument
#' @param ... Dots
#' @param z Last argument
#'
#' @usage NULL
f <- function(a, b, c, ..., z) NULL

#' @rdname f
f1 <- function(a, b, ..., z) {...}

#' @rdname f
f2 <- function(b, c, ..., z) {...}

\arguments{
\item{a}{First argument}

\item{b}{Second argument}

\item{c}{Third argument}

\item{...}{Dots}

\item{z}{Last argument}
}

This yields the desired result, but the obvious drawback is my package now includes an unnecessary unexported function.

Possible solution

#258 introduced the restriction that arguments must be documented in the same order as they appear in the formals of each documented function. The current implementation forces all arguments that appear only in the second function to be documented after all arguments that appear in the first function.

I would ease this restriction so that arguments are not reordered if the subset of @param tags for each function are in the same order as that function's formals, e.g. in the above example, a, b, c, ..., z would be a valid order because the subset a, b, ..., z matches the formals of f1 and the subset b, c, ..., z matches the formals of f2. The current reordering rule would be applied if the order of @param tags isn't compatible with the order of at least one function's formals.

I'd be happy to submit a PR if you think this change makes sense.

[hadley]

Yeah, I'd be happy to take a PR for this.