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

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