cc'ing the list for archive thread closure and possible additional comments.
My own preference leans toward simple default values as well, but if you are
hoping to warn students about alternative interpretations of function signatures
then be sure to point out the match.arg [1][2] convention also, in which the
function author can specify that the default value listed in the signature is a
vector of values that is interpreted to constrain the legal values that can be
specified for an argument and omitting any value for that argument defaults to
the function assuming the first value in the vector. This behavior relies on
some advanced features of R to work (how does the function refer to both the
user-specified argument values and the programmer's default vector at the
same time?) so it tends to look like magic to a beginner. I think it looks
inconsistent, but it is fairly common and students should be forewarned that it
represents one of the four (I think) ways default arguments might be portrayed
in a function signature: simple, missing, match.arg, and ellipsis.
Ellipsis arguments are indicated with ... and you have to read the documentation
(usually via See Also) to know what other function documentation you need to
read in order to find all possible argument and default signatures. The read.csv
function is a classic example where you need to know that it is a wrapper around
read.table and (almost) any of the arguments to read.table may be specified when
calling read.csv. (Read.csv forces some arguments to specific values to enforce
the definition of that format.)
[1] https://stat.ethz.ch/R-manual/R-devel/library/base/html/match.arg.html
[2] http://mazamascience.com/WorkingWithData/?p=1659
On November 5, 2018 3:38:14 AM PST, "St?phane Guillou"
<stephane.guillou at member.fsf.org> wrote:>Hi Jeff
>
>Thank you very much for the explanation.
>
>In my experience (i.e. from what I have seen so far in a few years of
>using R), this is such an unusual way to set a default that I thought
>it
>was a solid rule that arguments without a default value in "Usage"
>meant
>the user absolutely had to specify a value.
>
>Good to know that it is not a strict rule, but unfortunate it's making
>it slightly less straight-forward for my students! :)
>
>Cheers, all the best
>
>On 5/11/18 3:20 pm, Jeff Newmiller wrote:
>> The documentation describes the behavior of the program. The function
>signature shows how the arguments are declared. Both are correct.
>>
>> If you read an implementation [1] you will see that the missing()
>function is used to implement the described behavior, rather than using
>a default value for the argument. I don't know why this choice was made
>(changes in language over time?), but setting up argument default
>values is only one way to accomplish the described behavior.
>>
>> [1]
>https://github.com/wch/r-source/blob/trunk/src/library/utils/R/windows/download.file.R
>>
>> On November 4, 2018 4:56:19 PM PST, "St?phane Guillou"
><stephane.guillou at member.fsf.org> wrote:
>>> Hi there
>>>
>>> I was told by Martin Maechler that I should send this request to
>R-help
>>>
>>> rather than R-core, so here it is.
>>>
>>> I noticed that the download.file() documentation does not show a
>>> default
>>> value passed on to the `method` argument in the "Usage"
section,
>even
>>> though it is stated underneath that the default method is
`"auto"`.
>>>
>>> Does this need fixing?
>>>
>>> Cheers
--
Sent from my phone. Please excuse my brevity.