search

ropensci / BaseSet

Provides classes for working with sets
https://docs.ropensci.org/BaseSet
Other
10 stars 3 forks source link

rOpenSci review 1: Document passing parameters around #36

Closed llrs closed 4 years ago

llrs commented 4 years ago

Clarify annotations of "..."

Below is a list of every "..." documentation string:

mutate.R:12:       #' @param ... The logical predicates in terms of the variables of the sets
power_set.R:8:     #' @param ... Other arguments passed down if possible
GMT.R:8:           #' @param ... Other arguments passed to strsplit
group.R:8:         #' @param ... A logical condition to subset some elements
complement.R:80:   #' @param ... Other arguments passed to either ode{\link{complement_set}} or
group_by.R:12:     #' @param ... The logical predicates in terms of the variables of the sets
list.R:17:         #' @param ... objects, possibly named (currently ignored).
select.R:14:       #' @param ... The name of the columns you want to keep, remove or rename.
droplevels.R:36:   #' @param ... Other arguments, currently ignored.
data_frame.R:22:   #' @param ... Other arguments currently ignored.
filter.R:13:       #' @param ... The logical predicates in terms of the variables of the sets
union.R:19:        #' @param ... Other arguments.
add.R:92:          #' @param ... Other arguments passed along.
cartesian.R:11:    #' @param ... Other arguments passed down if possible
AllGenerics.R:328: #' @param ... Other arguments.
AllGenerics.R:352: #' @param ... Other arguments.
AllGenerics.R:372: #' @param ... Other arguments.
AllGenerics.R:392: #' @param ... Other arguments.
AllGenerics.R:413: #' @param ... Other arguments.
size.R:5:          #' @param ... Other arguments to filter which size should be shown.
arrange.R:14:      #' @param ... Comma separated list of variables names or expressions

Most of your documentation for "..." is fine. For example, "Comma separated list of variables names or expressions" tells me exactly what I need to know. Also, "Other arguments, currently ignored", is a perfectly acceptable. However, "Other arguments", is not helpful and I would have to dig through the source code to figure out what parameters are supported (and I've had to do exactly this for a lot of packages).

llrs commented 4 years ago

Corrected, and agree on the comment, they need to be clear enough for the user. I removed some ... from methods, others I got them to use. In any case the documentation was updated to explain and in some cases extend the examples of what they do.