R devel - Apr 2011 - question about assignment warnings for replacement methods

Hi,

I have seen several packages that with the most recent version of R are 
giving a warning like this:

Assignments in \usage in documentation object 'marginalData-methods':
marginalData(object) = value

I assume that this is to prevent people from making assignments in their 
usage statements (which seems completely understandable).  But what 
about the case above?  This is a person who just wants to show the 
proper usage for a replacement method.  IOW they just want to write 
something that looks like what you actually do when you use a 
replacement method.  They just want to show users how to do something 
like this:

replacementMethod(object) <- newValue


So is that really something that should not be allowed in a usage 
statement?


   Marc

On 05/04/2011 1:51 PM, Marc Carlson wrote:
> Hi,
>
> I have seen several packages that with the most recent version of R are
> giving a warning like this:
>
> Assignments in \usage in documentation object
'marginalData-methods':
> marginalData(object) = value
>
> I assume that this is to prevent people from making assignments in their
> usage statements (which seems completely understandable).  But what
> about the case above?  This is a person who just wants to show the
> proper usage for a replacement method.  IOW they just want to write
> something that looks like what you actually do when you use a
> replacement method.  They just want to show users how to do something
> like this:
>
> replacementMethod(object)<- newValue
>
>
> So is that really something that should not be allowed in a usage
> statement?
If replacementMethod was a replacement function, then

replacementMethod(object)<- newValue

is supposed to be fine.  But if it is an S3 method, it should be

\method{replacementMethod}{class}(object)<- newValue

and if it is an S4 method I think it should be

\S4method{replacementMethod}{signature_list}(object)<- newValue

(though the manual suggests using the S3 style, I'm not sure how literally
to take it).

Duncan Murdoch