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

[Henrik Bengtsson]

On 8/30/07, James W. MacDonald <jmacdon at med.umich.edu> wrote:
> 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.

You're approaching dangerous lands here ;)  Should methods be listed
under a class or a generic function.  Personally I think that is an
academic question, and often I do find it the former to be more
useful, because that is indeed how many packages are designed, i.e. we
do have an Image class or a GOHyperGParams with many methods coupled
to it.  In addition to "standalone" functions, there might be a few
functions with a wider purpose that operates across classes.  These
deserves there own item in the ToC/index too (I design my help index
to be a table of contents).

Some examples of help pages organized like this:

R.matlab:
http://rss.acs.unt.edu/Rdoc/library/R.matlab/html/00Index.html
R.oo:
http://rss.acs.unt.edu/Rdoc/library/R.oo/html/00Index.html

>
> 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' keywor

You can get a long way cleaning up help indices using
\keyword{internal}, and I believe there are quite a few developers
that are not aware of its existence.

Cheers

Henrik

>
> 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
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>