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

James W. MacDonald jmacdon at med.umich.edu
Thu Aug 30 16:06:35 CEST 2007

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


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.



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.
Affymetrix and cDNA Microarray Core
University of Michigan Cancer Center
1500 E. Medical Center Drive
7410 CCGC
Ann Arbor MI 48109

More information about the R-devel mailing list