R devel - Jan 2014 - Why do methods of "initialize" have no "srcref" attribute as other S4 mehtods?

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@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?

Thanks in advance

Markus

	[[alternative HTML version deleted]]

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