[R] potential issue in download.file() help page

[Jeff Newmiller]

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 using 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 using 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.