Many thanks for your helpful comments.
To over-simplify the previous discussion a bit, you are emphasising
that all the aliases written by promptMethods will be needed by future
versions of the help system, so it is important that they be included
in .Rd files documenting methods. I was saying that these aliases are
very verbose.
I am not the only one having trouble with the aliases. I have looked
through all the R packages that I know of that use S4 methods and
can't find even one example of a documented method which preserves all
the promptMethod style aliases. This may be partly because package
authors aren't sure what they should be doing, but I think it has to
be taken as a pretty strong statement from authors that the aliases
don't produce a workable result with the online help system as it
currently stands. The trouble I think is with the html package
contents page, which very quickly becomes too long and cluttered to be
useful if all the aliases are included.
Could we satisfy both needs, (i) to have a unique help alias
associated with each method and (ii) to have a package contents page
which is readable, by giving authors control over which aliases are
included on the contents page? Could we have a new command
\aliasonly{} for the .Rd files for aliases which are to be available
to the help system but not listed on the contents page? Authors could
use \alias{} for aliases which are to be listed and \aliasonly{} for
aliases which aren't.
It might also be helpful to have an optional argument, as in
\alias[optional.text]{}, to choose the text which is listed on the
package contents page.