[rkward-devel] R2HTML orphaned on CRAN

[Milan Bouchet-Valat]

Le dimanche 24 août 2014 à 11:46 +0200, Thomas Friedrichsmeier a écrit :
> 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.
Breaking the API because of a silly WARNING does not seem like the best
option to me. Why not a) instead, since it has no effect on the actual
code, just on the docs? The doc page makes it obvious anyway that it's
not a S3 method.


Regards