[Rd] Why do methods of "initialize" have no "srcref" attribute as other S4 mehtods?
Duncan Murdoch
murdoch.duncan at gmail.com
Wed Jan 8 01:11:35 CET 2014
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
More information about the R-devel
mailing list