[rkward-devel] R2HTML orphaned on CRAN

[Thomas Friedrichsmeier]

Hi!

On Sunday 24 August 2014 10:20:56 Milan Bouchet-Valat wrote:
> Actually I also need a setter function in my RcmdrPlugin.temis package,
> so I'll add both a getter an a setter. The NEWS will have to mention
> that this update breaks API anyway.

While we're at breaking the API: I've taken care of the other two notes, 
except for:

> * checking Rd \usage sections ... NOTE
> 
> S3 methods shown with full name in documentation object 'HTML.cormat':
>   ‘HTML.cormat’
> 
> The \usage entries for S3 methods should use the \method markup and not
> their full name.

Now, HTML.cormat.Rd specifically says:

> Although the class \sQuote{cormat} is not defined, the function is called to
> \code{HTML.cormat}, to highlight the fact it should be called only with a
> correlation matrix.

So, using \method markup would seem somewhat wrong, even if it would shut up 
the warning without too bad side-effects. Googling reveals, R2HTML 
is not the first package with that problem(*). There appears to be no 
workaround other than renaming the function. In fact, that may actually be 
reasonable, because HTML.cormat *will* become an S3-method for "cormat" 
objects, as soon as any package defines that class (not necessarily in a 
compatible way).

I'm uncertain, whether we should
a) use S3-method markup, anyway
b) rename HTML.cormat to HTMLcormat, breaking the API (although of course we 
could keep a deprecated HTML.cormat along with a))
c) Ignore the note, assuming that CRAN maintainers will be ok with it.

I tend to think, b) may be the best option after all.

Regards
Thomas

(*): e.g.:
- http://r.789695.n4.nabble.com/R-CMD-check-non-S3-method-warning-td4576398.html
- http://r.789695.n4.nabble.com/S3-methods-with-full-name-in-documentation-td4490309.html
- http://r.789695.n4.nabble.com/Need-to-tell-R-CMD-check-that-a-function-qr-R-is-not-a-method-td4642506.html