From murdoch.duncan at gmail.com  Wed Jan  8 22:07:22 2014
From: murdoch.duncan at gmail.com (Duncan Murdoch)
Date: Wed, 08 Jan 2014 16:07:22 -0500
Subject: [Rd] Why do methods of "initialize" have no "srcref" attribute
 as other S4 mehtods?
In-Reply-To: <CAOAQ5srxggq=XJ3snuW5x_1bYa_=qcTHuJTi_0h0X9psX5Lp3Q@mail.gmail.com>
References: <CAOAQ5sqk3BxSh=hzB5Z-uSVLEdNbkDqSwrj7BwBzaGi+j6Tn8Q@mail.gmail.com>	<52CC97B7.8080308@gmail.com>
	<CAOAQ5srxggq=XJ3snuW5x_1bYa_=qcTHuJTi_0h0X9psX5Lp3Q@mail.gmail.com>
Message-ID: <52CDBE0A.1090305@gmail.com>

On 14-01-08 6:51 AM, Markus M?ller wrote:
> Thank You very much. This is a great help.
> I would never ever have thought of either unRematchDefinition or getSrcref.
> I will incorporate this new insight and report about any further
> discoveries (or problems leading to them ;-))

After thinking about this a while, I decided that it's really a bug that 
getSrcref didn't do this automatically.  So now it does (in R-patched 
and R-devel).

Duncan Murdoch

>
> Thanks again
> Markus
>
>
> 2014/1/8 Duncan Murdoch <murdoch.duncan at gmail.com
> <mailto:murdoch.duncan at gmail.com>>
>
>     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
>
>
>



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