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

[Oleg Sklyar]

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