[Rd] 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]]
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Why do methods of "initialize" have no "srcref" attribute as other S4 mehtods?
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 ;-))
Thanks again
Markus
2014/1/8 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@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
>
>
>
[[alternative HTML version deleted]]
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
[Rd] Which functions are there to parse a NAMESPACE file (without installing the package)
For the purpose of automatic documentation, I want to parse a NAMESPACE file of the package to be documented. I want to know the contents: exportedClasses , exportedMethods and so on to be able to hide the part of the documentation not exposed in the NAMESPACE file. Up to now I am parsing the file myself and do some regexpr stuff to get what i want. It would however be much nicer to use the facilities that R itself probably provides, so that i could handle everything R can and remove the unnecessary duplication. (Since R hast to look at the NAMESPACE while e.g. building a package from source those parsers should be certainly there) I just don't know where to look for them. Thanks in advance Markus [[alternative HTML version deleted]] __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Which functions are there to parse a NAMESPACE file (without installing the package)
Cool It works ;-) Thanks a lot. 2014/1/21 Peter Meilstrup > Try the function parseNamespaceFile in base. Not documented but its > output should be understandable. > > Peter > > On Tue, Jan 21, 2014 at 5:41 AM, Markus Müller > wrote: > > For the purpose of automatic documentation, I want to parse a NAMESPACE > > file of the package to be documented. > > > > I want to know the contents: > > exportedClasses , exportedMethods and so on > > > > to be able to hide the part of the documentation not exposed in the > > NAMESPACE file. > > > > Up to now I am parsing the file myself and do some regexpr stuff to get > > what i want. > > It would however be much nicer to use the facilities that R itself > probably > > provides, so that i could handle everything R can and remove the > > unnecessary duplication. > > > > (Since R hast to look at the NAMESPACE while e.g. building a package from > > source those parsers should be certainly there) > > > > I just don't know where to look for them. > > > > Thanks in advance > > Markus > > > > [[alternative HTML version deleted]] > > > > __ > > R-devel@r-project.org mailing list > > https://stat.ethz.ch/mailman/listinfo/r-devel > [[alternative HTML version deleted]] __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
