[inlinedocs] tabs before comments and symbols, S3 methods

[Keith Ponting]

Hi Thomas,

Thankyou for this - I have just got back from leave and will have a look
when I have some time.

The point about generics is that:
1) They may be "local" - defined purely within the package, as in
"getAlignment" referred to by Jim Bullard in another e-mail, or "global"
- defined elsewhere as with the "show" method for example.
2) They usually have common (sets of) arguments, and on the "don't
repeat yourself" principle, I would like to document such arguments once
only and automatically copy the documentation to other versions of the
same generic function.
3) They can be defined as an un-named function entirely within the
setMethod(S3) call or as the name of a previously defined function. The
latter is where the concept of linked documentation came from - the
documentation for the previously defined function (parent) gets
automatically copied into documentation for the generic.

Therefore, what is currently in place does the following when a generic
is encountered while processing a file (this could be package, but then
first time is not particularly well defined):
A) If there are no previous methods for that generic, (the generic is
previously unseen), that instance is taken to be the "defining instance"
on the (probably invalid) assumption that one would define the most
generic version first, then more specific implementations for particular
classes.
B) Documentation for subsequent (assumed more specific) versions of the
generic links back to that first instance and will inherit any
components of the documentation unless overridden. (Component of
documentation= function argument or other documentation section, such as
note or value)

To give a concrete example, I wanted a generic "getSettings" for a class
hierarchy, so wrote the following:

setMethodS3("getSettings","HitSelector",function # HitSelector parameter
settings
### Returns a list describing the parameter settings of the
### \code{\link{HitSelector}} object. For the base class this list is
"not
### very interesting" (empty).  Derived \code{\link{HitSelector}}
classes
### should "roll their own".
(x, ##<< inherits from \code{\link{R.oo}} class
\code{\link{HitSelector}}
 ...)  ##<< ignored - required by \code{\link{setMethodS3}}
{
  ##note<< This may also be accessed as \code{object$settings}.
  invisible(list())
### Returns a named list describing class parameter settings.
})
setMethodS3("getSettings","HitThresh",function # HitThresh parameter
settings
### Returns a list describing the parameter settings of the
### \code{\link{HitThresh}} object.
(x, ##<< inherits from \code{\link{R.oo}} class \code{\link{HitThresh}}
 ...)  ##<< ignored - required by \code{\link{setMethodS3}}
{
  invisible(list(maxdist=x$threshold))
})
setMethodS3("getSettings","HitCeiling",function # HitCeiling parameter
settings
(x, ##<< inherits from \code{\link{R.oo}} class \code{\link{HitCeiling}}
 ...)  ##<< ignored - required by \code{\link{setMethodS3}}
{
  res <- list(ceiling=x$threshold)
  if ( is.finite(x$tail) ) res$tail <- x$tail
  invisible(res)
})

The base class "HitSelector" comes first, so is the "defining instance"
of the previously unseen generic "getSettings". Subsequent getSettings
do not have "note" and "value" sections and inherit those via "linked
documentation" from the previous (or parent) instance. (I should also
have inherited the repetitive "ignored" lines.) Parent is transitive, so
had I written:

baseSettings <- function # HitSelector parameter settings
### Returns a list describing the parameter settings of the
### \code{\link{HitSelector}} object. For the base class this list is
"not
### very interesting" (empty).  Derived \code{\link{HitSelector}}
classes
### should "roll their own".
(x, ##<< inherits from \code{\link{R.oo}} class
\code{\link{HitSelector}}
 ...)  ##<< ignored - required by \code{\link{setMethodS3}}
{
  ##note<< This may also be accessed as \code{object$settings}.
  invisible(list())
### Returns a named list describing class parameter settings.
}
setMethodS3("getSettings","HitSelector",baseSettings)

The effect would have been pretty much the same, except there would now
also be documentation for the baseSettings function and all the
components of "baseSettings" documentation would magically appear as the
documentation for getSettings.HitSelector.

HTH,

Keith

Keith Ponting
Aurix Ltd, Malvern WR14 3SZ  UK


> -----Original Message-----
> From: Thomas Wutzler [mailto:twutz at bgc-jena.mpg.de]
> Sent: 30 April 2010 13:45
> To: Keith Ponting
> Cc: inlinedocs-support at r-forge.wu-wien.ac.at
> Subject: Re: [inlinedocs] tabs before comments and symbols, S3 methods
> 
> Dear Keith,
> 
> thanks to you for implementing the setMethodS3 support.
> 
> I tried to understand how it is applied and added a test project
sillyS3
> to the test directory, which discussion can be based upon.
> 
> In the code of extract.file.parse you comment
>       ##details<< The \code{setMethodS3} calls introduce additional
>       ## complexity: they will define an additional S3 generic (which
>       ## needs documentation to avoid warnings at package build time)
>       ## unless one already exists. This also is handled by "linking"
>       ## documentation. A previously unseen generic is linked to the
>       ## first defining instances, subsequent definitions of that gen.
>       ## also link back to the first defining instance.
> 
> I do not quite understand.
> What is an "linking documentation", "unseen generic", and what an
"first
> defining instance"?
> 
> In the sillyS3 toy example, I see that the parse result includes an
> entry for the generic function. However, it does not (yet?) effect the
> generated documentation. Hence R CMD check complains about an
> undocumented function.
> 
> I would be glad about some guidance.
> 
> Best regards
> Thomas
> 
> 
> 
> 
> 
>