R devel - Jul 2011 - Circumventing code/documentation mismatches ('R CMD check')

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?

Sincerely, Joh

Prof Brian Ripley wrote:
> On Mon, 4 Jul 2011, Johannes Graumann wrote:
> 
>> Hello,
>>
>> I'm writing a package am running 'R CMD check' on it.
>>
>> Is there any way to make 'R CMD check' not warn about a
missmatch between
>> 'NA_character_' (in the function definition) and 'NA'
(in the
>> documentation)?
> 
> Be consistent ....  Why do you want incorrect documentation of your
> package?  (It is not clear of the circumstances here: normally 1 vs 1L
> and similar are not reported if they are the only errors.)
> 
> And please do note the posting guide
> 
> - this is not really the correct list
> - you were asked to give an actual example with output.

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