[Rd] suggesting \alias* for Rd files (in particular for S4 method documentation)

[James W. MacDonald]

I think Oleg makes a good point here, and I don't see how his suggestion 
would hide any documentation.

As an example, start R and then open the HTML help page, and go to the 
Category package. If you click on any one of

annotation,GOHyperGParams-method
categoryName,GOHyperGParams-method
conditional,GOHyperGParams-method
conditional<-,GOHyperGParams-method
GOHyperGParams-class
ontology,GOHyperGParams-method
ontology<-,GOHyperGParams-method
show,GOHyperGParams-method

You will be sent to the same help page, which contains the documentation 
for all those specific methods. The question here is do we really this 
many-to-one relationship in the HTML pages?

In general (Oleg notwithstanding), I think the HTML pages are used 
primarily by new users to R, and having such an overload on the index 
page for this package is IMO a disservice to these people. Having just 
one link, GOHyperGParams-class, or possibly an additional 
GOHyperGParams-methods would be much cleaner.

There already exists a mechanism for keeping internal methods from 
showing up in the HTML indices: adding \keyword{internal} to the end of 
the .Rd file. However, this hides all the \alias{} (and \name{}) 
entries, so won't do what Oleg wants unless you have two separate .Rd 
files, one containing the \alias{} names you want to show, and the other 
with the 'internal' keyword.

Best,

Jim



Martin Morgan wrote:
> Hi Oleg --
> 
> On the usefulness of write.image,Image,character-method, in the end I
> really want documentation on specific methods. Maybe the issue is one
> of presentation?
> 
> write.image
>     Image,character-method
>     Image,missing-method
> 
> or, in a little more dynamic world, a '+' in front of write.image to
> expand the methods list.
> 
> alias* is a little strange, because it implies you're writing
> documentation, but then hiding easy access to it! This is not a strong
> argument against introducing alias*, since no one is forced to use it.
> 
> It also suggests that your documentation is organized by generic,
> which might also be a bit unusual -- I typically have an object (e.g.,
> an Image) and wonder what can be done to it (e.g., write it to
> disk). This suggests associating method documentation with object
> documentation. Multiple dispatch might sometimes make this difficult
> (though rarely in practice?). Separately documenting the generic is
> also important.
> 
> Martin
> 
> Oleg Sklyar <osklyar at ebi.ac.uk> writes:
> 
>> Hi,
>>
>> I do not know if everybody finds index pages of the html-formatted R
>> help useful, but I know I am at least not the only one who uses them
>> extensively to get the overview of functions and methods in a package
>> (even for my own package). Problems arise, however, if a lot of S4
>> methods need to be documented blowing out the index with (generally
>> irrelevant) entries like:
>>
>> write.image,Image,missing-method
>> write.image,Image,character-method
>>
>> instead of a simple "write.image". I also do not believe anyone really
>> does something like "help(write.image,Image,missing-method)" on the
>> command line, thus these structures are more for internal linking than
>> for users.
>>
>> Therefore, I would suggest to introduce a modification of the \alias
>> keyword, that would do all the same as the standard \alias keyword, yet
>> it would *hide* that particular entry from the index. Reasonable
>> construction could be something like \alias*{} yielding
>>
>> \alias{write.image}
>> \alias*{write.image,Image,missing-method}
>> \alias*{write.image,Image,character-method}
>>
>> Alternatively:
>>
>> \alias{write.image}
>> \alias[hide]{write.image,Image,missing-method}
>> \alias[hide]{write.image,Image,character-method}
>>
>> Any comments?
>>
>> For me, the current way around is to avoid usage sections with \S4method
>> all together, substituting them with pairs of
>>
>> \section{Usage}{\preformatted{
>> }}
>> \section{Arguments}{
>> }
>>
>> and putting all aliases marked above with * into internals, which is
>> definitely not the best way of going around documentation and
>> code/documentation mismatches.
>>
>> Best regards,
>> Oleg
>>
>> -- 
>> Dr. Oleg Sklyar * EBI-EMBL, Cambridge CB10 1SD, UK * +44-1223-464466
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
> 

-- 
James W. MacDonald, M.S.
Biostatistician
Affymetrix and cDNA Microarray Core
University of Michigan Cancer Center
1500 E. Medical Center Drive
7410 CCGC
Ann Arbor MI 48109
734-647-5623