[Rd] [R] documenting s4 methods in package
Duncan Murdoch
murdoch at stats.uwo.ca
Fri Apr 7 13:54:18 CEST 2006
There are usually two directories involved in an install: the source
directory and the install directory in R_HOME/library.
The INSTALL procedure builds the package (usually in place in Windows,
I'm not sure if that's the case in Unix) and installs it into the
install directory by copying those files necessary to use it. REMOVE
removes the install directory, cleaning up R_HOME/library, but not
touching your source.
"R CMD install --clean" cleans up the files from your source directory
instead of doing the install. (It won't delete your source, just the
intermediate files.)
There are a few "usually"s up there, because it is also possible to
install from a tarball or a zip file or in place, etc. From a tarball
the procedure is a lot like what is described above after extracting to
a temporary source directory; a zip is a copy of the final install
directory, so most of the work has already been done.
Duncan Murdoch
On 4/7/2006 7:21 AM, Steven Lacey wrote:
> Yes. I am reinstalling the package, and your explanations both hit on what
> is likely going on. However, before reinstalling the package with R CMD
> INSTALL --build I call R CMD REMOVE, which I thought meant starting from
> scratch. That is, there would be no memory in the help files as to what was
> there before. I need to figure out more precisely what REMOVE is doing and
> what the --clean option will do.
>
> I assume there is something wrong with how I am using the package
> development system. I am neophyte on these matters and am in no position to
> evaluate how it is done. I am trying to figure out how it works, and your
> help is greatly appreciated!
>
> Steve
>
>
> -----Original Message-----
> From: Prof Brian Ripley [mailto:ripley at stats.ox.ac.uk]
> Sent: Friday, April 07, 2006 6:59 AM
> To: Steven Lacey
> Cc: 'Duncan Murdoch'
> Subject: Re: [R] documenting s4 methods in package
>
>
> A possible scenario:
>
> You are re-installing a package you have not changed otherwise changed and
> without using --clean.
>
> The R CMD INSTALL does not need to reprocess the older help files to chm,
> since it already has them in the package source directory. It does not
> have the other types except in the installation directory, which was moved
> away unless you used --unsafe.
>
> But you have not mentioned re-installation.
>
>
> On Fri, 7 Apr 2006, Prof Brian Ripley wrote:
>
>> On Fri, 7 Apr 2006, Steven Lacey wrote:
>>
>>> Why do some functions build chm help and others do not? Is there
>>> something in the .Rd file that specifies this?
>> `functions' never build help of any type, and nothing in the .Rd file
>> controls the conversion type.
>>
>> Which types of help are built is controlled by options of R CMD
>> INSTALL and by the settings in MkRules.
>>
>> You will need to give us a reproducible example, but please use the
>> R-devel
>> list for code development questions (after doing the homework the posting
>> guide asks for).
>>
>> SInce we supply a documented process that works smoothly for
>> installing
>> several hundred packages, please give us the credit of supplying you with
> a
>> mature system and looking first for the problems in your own usage of it.
>>
>>
>>> Thanks,
>>> Steve
>>>
>>> -----Original Message-----
>>> From: Duncan Murdoch [mailto:murdoch at stats.uwo.ca]
>>> Sent: Tuesday, April 04, 2006 2:22 PM
>>> To: Steven Lacey
>>> Cc: 'Thomas Lumley'; r-help at stat.math.ethz.ch
>>> Subject: Re: [R] documenting s4 methods in package
>>>
>>>
>>> On 4/4/2006 1:58 PM, Steven Lacey wrote:
>>>> Thomas,
>>>>
>>>> Correction! If I remove the \seealso line the missing ~~fun~~
>>>> disppears (thank you!), but now "chm" appears at the end of the line
>>>> decribing the help page building. Most lines do not have that, only
>>>> "text htm1 latex example". What does the chm signify and how does
>>>> one get rid of it?
>>> "chm" indicates that you have built a compiled HTML version of your
>>> man page. It will be shown in Windows if you ask for help after
>>> options(chmhelp=TRUE).
>>>
>>> You can edit the MkRules file to disable production of this kind of
>>> help page.
>>>
>>> Duncan Murdoch
>>>> Thanks,
>>>> Steve
>>>>
>>>> -----Original Message-----
>>>> From: Steven Lacey [mailto:slacey at umich.edu]
>>>> Sent: Tuesday, April 04, 2006 1:54 PM
>>>> To: 'Thomas Lumley'
>>>> Cc: 'r-help at stat.math.ethz.ch'
>>>> Subject: RE: [R] documenting s4 methods in package
>>>>
>>>>
>>>> Thomas,
>>>>
>>>> If I delete the \seealso section, I still get the same strange
>>>> behavior. Shouldn't removing that line fix the problem?
>>>>
>>>> Thanks,
>>>> Steve
>>>>
>>>> -----Original Message-----
>>>> From: Thomas Lumley [mailto:tlumley at u.washington.edu]
>>>> Sent: Tuesday, April 04, 2006 10:13 AM
>>>> To: Steven Lacey
>>>> Cc: r-help at stat.math.ethz.ch
>>>> Subject: Re: [R] documenting s4 methods in package
>>>>
>>>>
>>>> On Tue, 4 Apr 2006, Steven Lacey wrote:
>>>>
>>>>> Hi,
>>>>>
>>>>> I have written a package that contains many s4 generic functions
>>>>> and associated methods. I am having a lot of trouble getting R to
>>>>> build the help pages for these generic functions without reporting,
>>>>> "missing
>>>>> link(s): ~~fun~~, which means that it cannot find the appropriate
>>>>> function when code in the example section of the help is run.
>>>>> Right?
>>>> No. It means that you still have \link{~~fun~~} in the \seealso
>>>> section.
>>>>
>>>> -thomas
>>>>
>>>>
>>>>> After some playing around I can get it to build the help without
>>>>> missing a link, but often I am not sure what I have done to correct
>>>>> the "problem" and it takes a lot of time.
>>>>>
>>>>> For instance, I had the package build the help without missing a
>>>>> function link. I then added a argument to two different functions
>>>>> and updated the corresponding .rd help files and now when R build
>>>>> the help pages it reports "missing link(s): ~~fun~~. What is going
>>>>> on?
>>>>>
>>>>> Below is the code from the help file and the associated s4 method.
>>>>>
>>>>> Any help would be greatly appreciated.
>>>>>
>>>>> Steve
>>>>>
>>>>> GENERIC FUNCTION AND METHODS
>>>>>
>>>>> setGeneric("getRemovedDf.OAD",function(x,y,z,simplify=TRUE,descrip=
>>>>> FA
>>>>> L
>>>>> SE){st
>>>>> andardGeneric("getRemovedDf.OAD")})
>>>>>
>>>>> setMethod("getRemovedDf.OAD","status.or.rm.v1",
>>>>> function(x,y,z,simplify,descrip){
>>>>> if(length(0">x at removed) <mailto:x at removed)> >0){
>>>>> pred <- unlist(lapply(x at removed,function(x)x[1]))
>>>>> resp <- unlist(lapply(x at removed,function(x)x[2]))
>>>>> out <- data.frame(pred,resp)
>>>>> names(out) <- c(y,z)
>>>>> return(out)
>>>>> } else {
>>>>> return(data.frame())
>>>>> }
>>>>> }
>>>>> )
>>>>>
>>>>> setMethod("getRemovedDf.OAD","sa",
>>>>> function(x,y,z,simplify,descrip){
>>>>> i <-
>>> unlist(lapply(x at outlier.removal,function(x)length(x at removed)))
>>>>> if(all(i==0)){
>>>>> return(list())
>>>>> } else {
>>>>> if(simplify) x at outlier.removal[seq(along=i)[i==0]]
>>>>> <mailto:x at outlier.removal[seq(along=i)[i==0]]<-NULL> <-NULL
>>>>> tmp <-
>>>>>
> lapply(x at outlier.removal,getRemovedDf.OAD,x at predictorName,x at responseName)
>>>>> if(descrip){
>>>>> f <-
>>> as.data.frame(descrip[!"history"%in%names(x at descrip)])
>>>>> return(lapply(tmp,function(x)cbind(f,x)))
>>>>> } else {
>>>>> return(tmp)
>>>>> }
>>>>> }
>>>>> }
>>>>> )
>>>>>
>>>>>
>>>>> MAN FILE
>>>>> \name{getRemovedDf.OAD}
>>>>> \alias{getRemovedDf.OAD}
>>>>> %- Also NEED an '\alias' for EACH other topic documented here.
>>>>> \title{ ~~function to do ... ~~ } \description{ ~~ A concise (1-5
>>>>> lines) description of what the function does. ~~ }
>>>>> \usage{
>>>>> getRemovedDf.OAD(x, y, z, simplify = TRUE, descrip=FALSE) }
>>>>> %- maybe also 'usage' for other objects documented here.
>>>>> \arguments{
>>>>> \item{x}{ ~~Describe \code{x} here~~ }
>>>>> \item{y}{ ~~Describe \code{y} here~~ }
>>>>> \item{z}{ ~~Describe \code{z} here~~ }
>>>>> \item{simplify}{ ~~Describe \code{simplify} here~~ }
>>>>> \item{descrip}{ ~~Describe \code{descrip} here~~ }
>>>>> }
>>>>> \details{
>>>>> ~~ If necessary, more details than the __description__ above ~~
>>>>> }
>>>>> \value{
>>>>> ~Describe the value returned
>>>>> If it is a LIST, use
>>>>> \item{comp1 }{Description of 'comp1'}
>>>>> \item{comp2 }{Description of 'comp2'}
>>>>> ...
>>>>> }
>>>>> \references{ ~put references to the literature/web site here ~ }
>>>>> \author{ ~~who you are~~ }
>>>>> \note{ ~~further notes~~ }
>>>>>
>>>>> ~Make other sections like Warning with \section{Warning }{....} ~
>>>>>
>>>>> \seealso{ ~~objects to See Also as \code{\link{~~fun~~}}, ~~~ }
>>>>> \examples{
>>>>> ##---- Should be DIRECTLY executable !! ----
>>>>> ##-- ==> Define data, use random,
>>>>> ##-- or do help(data=index) for the standard data sets.
>>>>>
>>>>> ## The function is currently defined as
>>>>> function(x,y,z,simplify=TRUE,descrip=FALSE){standardGeneric("getRem
>>>>> ov
>>>>> e
>>>>> dDf.OA
>>>>> D")}
>>>>> }
>>>>> \keyword{ ~kwd1 }% at least one, from doc/KEYWORDS
>>>>> \keyword{ ~kwd2 }% __ONLY ONE__ keyword per line
>>>>>
>>>>>
>>>>> [[alternative HTML version deleted]]
>>>>>
>>>>> ______________________________________________
>>>>> R-help at stat.math.ethz.ch mailing list
>>>>> https://stat.ethz.ch/mailman/listinfo/r-help
>>>>> PLEASE do read the posting guide!
>>>>> http://www.R-project.org/posting-guide.html
>>>>>
>>>> Thomas Lumley Assoc. Professor, Biostatistics
>>>> tlumley at u.washington.edu University of Washington, Seattle
>>>>
>>>> ______________________________________________
>>>> R-help at stat.math.ethz.ch mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-help
>>>> PLEASE do read the posting guide!
>>>> http://www.R-project.org/posting-guide.html
>>> ______________________________________________
>>> R-help at stat.math.ethz.ch mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-help
>>> PLEASE do read the posting guide!
>>> http://www.R-project.org/posting-guide.html
>>>
>>
>
More information about the R-devel
mailing list