Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Arguments order with @inheritParams #63

Closed
sophieb opened this issue Nov 29, 2011 · 5 comments · Fixed by #258
Closed

Arguments order with @inheritParams #63

sophieb opened this issue Nov 29, 2011 · 5 comments · Fixed by #258

Comments

@sophieb
Copy link

@sophieb sophieb commented Nov 29, 2011

When using @inheritParams, the arguments are not necessarily listed in the right order in the .Rd file created. By right order, I mean the argument order in the usage section.

Here is an example. Let's say I have two functions:

fct1 <- function(r, K){...}
fct2 <- function(r, p, K){...}

In the roxygen2 documentation of the first function I use the following tags:

' @param r description of argument r

' @param K description of argument K

For the second function, I use the following tags:

' @param p description of argument p

' @inheritParams fct1

After processing my code with roxygenize, the .Rd file for the function fct2 presents the arguments in the following order: p, r, K (not r, p, K as I would have expected).

@BrianDiggs
Copy link

@BrianDiggs BrianDiggs commented Nov 29, 2011

In general, it seems that roxygen2 will list parameters in the order they are mentioned in the @param documentation. In this case, p is mentioned first, then r and K (by reference). It seems that some authors like to document their parameters in a different order than they are listed in the function. I find it odd, but I assume it is deliberate. If you want to preserve this ability, perhaps the way to do this is with a flag (@sortParams?) that if defined will reorder the entries in the Rd file to be the same as in the function declaration(s). In the case of multiple functions being documented in the same Rd file, I would guess that the order would be all the parameters in order for the first function defined, then the parameters for the second function (that were not already defined) in order, etc.

@hadley
Copy link
Member

@hadley hadley commented Aug 27, 2012

As Brian mentions, this is a general problem. It should be possible to automatically sort them so they always match the order of the usage.

@hadley
Copy link
Member

@hadley hadley commented Nov 4, 2013

Although it's challenging when you have multiple usage statements. I guess you need to parse the usage statements, and then order by there first appearance? Also challenging if you're documenting multiple parameters in a single params (e.g. @params x,y ...). This may be beyond the current scope of roxygen2.

@krlmlr
Copy link
Member

@krlmlr krlmlr commented Jun 17, 2014

I'll attempt an implementation by changing process_inherit_params so that the order of the \param tags matches the order in the formals. In a first version, the reordering will be applied only if it can be determined without doubt (i.e., same formals and params, only order is wrong). We can think of enhancements later.

@hadley: Do you think the order should be imposed also for functions without @inheritParams?

@hadley
Copy link
Member

@hadley hadley commented Jun 17, 2014

Yes, ideally docs should always be in same order as arguments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

4 participants