[Rd] Why do methods of "initialize" have no "srcref" attribute as other S4 mehtods?

[Duncan Murdoch]

On 14-01-07 2:40 PM, Markus Müller wrote:
> For documentation we use a system that generates Rd files from special
> comments in the code. (inlinedocs).
> It is crucial to be able to get the defining source code for objects like
> methods to extract the comments from it.
>
> Here is an R session that shows how this works for several kinds of methods
> and (at the end of the session) how if fails for methods of "initialize"
>
>> require("methods")
>> setGeneric( "myGen",function(arg){standardGeneric("myGen")})
> [1] "myGen"
>> setMethod(
> +   f="myGen",
> +   signature="numeric",
> +   definition=function # a function with comments in its source
> +     ### that are used to document it with inlinedocs
> +     (arg ##<< another special comment for the argument
> +     ){
> +       2*arg
> +       ### a description for the return value
> +     }
> + )
> [1] "myGen"
>
> we can get the whole function definition with comments back
> by the following snippet:
>> attr(getMethod("myGen","numeric"),"srcref")
> function # a function with comments in its source
>      ### that are used to document it with inlinedocs
>      (arg ##<< another special comment for the argument
>      ){
>        2*arg
>        ### a description for the return value
>      }
>>
>
> this also works for operators
>
>> setMethod("$",
> +     signature(x = "MyClass"),
> +     function
> +     (x,   ##<< first arg
> +      name ##<< second ag
> +      ) { }
> + )
> [1] "$"
>> attr(getMethod("$","MyClass"),"srcref")
> function
>      (x,   ##<< first arg
>       name ##<< second ag
>       ) { }
>>
>> setClass(
> +    Class="MyClass",
> +    representation(
> +    val="numeric"
> +    )
> + )
>
> It works also for other functions already defined:
>
>> setGeneric("plot")
> [1] "plot"
>> setMethod("plot",
> +     signature(x = "MyClass"),
> +     function # a comment
> +     (x, y, ...)
> +     {
> +         stop("need a definition for the method here")
> +     }
> + )
> [1] "plot"
>> attr(getMethod("plot","MyClass"),"srcref")
> function # a comment
>      (x, y, ...)
>      {
>          stop("need a definition for the method here")
>      }
>>
>
> However if we overload initialize there is no "srcref" attribute:
>
>> setMethod(
> +     f="initialize",
> +     signature="MyClass",
> +     definition=function # here are also comments but we can not retrieve
> them
> +     (.Object,value){
> +       .Object at val<- value
> +       return(.Object)
> +     }
> + )
> [1] "initialize"
>>
>> attr(getMethod("initialize","MyClass"),"srcref")
> NULL
>
> Is there a reason for this behavior, and more important still,
> Ist there a way to get at the source of my constructors to document them
> automatically?

I don't know the why of the design, but the comments are there, just not 
where you were looking.  You can get them as follows:

f <- getMethod("initialize", "MyClass")
getSrcref(unRematchDefinition(f))

This should work for the other cases too, where unRematchDefinition does 
nothing.  I don't know if there are any cases where it will fail, but if 
there are, please let me know.

Probably the getSrcref function should do this automatically when it 
sees that f is a method definition, but I'll wait to hear if it's the 
wrong approach.

Duncan Murdoch