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

[peter dalgaard]

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