Re: [Rd] Circumventing code/documentation mismatches ('R CMD check')

From: peter dalgaard <pdalgd_at_gmail.com>
Date: Tue, 05 Jul 2011 08:59:26 +0200

On Jul 5, 2011, at 08:00 , Johannes Graumann wrote:

> Hello,
>
> As prompted by B. Ripley (see below), I am transfering this over from R-User
> ...
>
> For a package I am writing a function that looks like
>
> test <- function(Argument1=NA){
> # Prerequisite testing
> if(!(is.na(Argument1))){
> if(!(is.character(Argument1))){
> stop("Wrong class.")
> }
> }
> # Function Body
> cat("Hello World\n")
> }
>
> Documentation of this is straight forward:
>
> ...
> \usage{test(Argument1=NA)}
> ...
>
> However writing the function could be made more concise like so:
>
> test2 <- function(Argument1=NA_character_){
> # Prerequisite testing
> if(!(is.character(Argument1))){
> stop("Wrong class.")
> }
> # Function Body
> cat("Hello World\n")
> }
>
> To prevent confusion I do not want to use 'NA_character_' in the user-
> exposed documentation and using
>
> ...
> \usage{test2(Argument1=NA)}
> ...
>
> leads to a warning reagrding a code/documentation mismatch.
>
> Is there any way to prevent that?

You don't want to do that...

That strategy breaks if someone passes the documented "default" explicitly, which certainly _causes_ confusion rather than prevent it. I.e.

test2(NA) # fails

test3 <- function(a=NA) test2(a) # 3rd party code might build on your function test3() # fails

If your function only accept character values, even if NA, then that is what should be documented. In the end, you'll find that an explicit is.na() is the right thing to do.

-- 
Peter Dalgaard
Center for Statistics, Copenhagen Business School
Solbjerg Plads 3, 2000 Frederiksberg, Denmark
Phone: (+45)38153501
Email: pd.mes_at_cbs.dk  Priv: PDalgd_at_gmail.com

______________________________________________
R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Received on Tue 05 Jul 2011 - 07:05:05 GMT

This quarter's messages: by month, or sorted: [ by date ] [ by thread ] [ by subject ] [ by author ]

All messages

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Tue 05 Jul 2011 - 11:00:06 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive