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

[Oleg Sklyar]

Maybe I need to add a comment.

The idea is not to avoid providing documentation for specific methods,
rather to be able to selectively hide things in the index keeping the
index sane. On the developer discretion, as generally I think the
developer should decide what the user can see and how.

It would still bring up the help page on typing the help command e.g.
help(write.image,Image,missing-method) and it would still allow the
corresponding referencing. Moreover it would allow to specifically show
those method definitions, which *are* important rather than all that
exist.

There are not so many cases where the generic is often reused with
different classes across different packages and in those cases it is
truly reasonable to have a comprehensive help listing the signatures in
the index as well. But take the above "write.image" -- I doubt there is
another implementation of this generic anywhere in the R world and my
current documentation would have *one* page for all -- the generic and
all the methods, so why to have 3 visible links in the index that do not
really give more information than the page itself (where all use cases
are listed).

I however agree that the indented structure as Martin suggested would be
a big step forward already.

James: moving things to internals does not work as if you provide
\S4method clause you *must* provide a corresponding alias, otherwise you
get a check warning and for example on Bioconductor you will have
problems with BioC maintainers, and it is good so ;-)

Best,
Oleg

On Thu, 2007-08-30 at 10:06 -0400, James W. MacDonald 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.
> 
> 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
> >>
> >> ______________________________________________
> >> R-devel at r-project.org mailing list
> >> https://stat.ethz.ch/mailman/listinfo/r-devel
> > 
> 
-- 
Dr. Oleg Sklyar * EBI-EMBL, Cambridge CB10 1SD, UK * +44-1223-464466