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

From: Martin Morgan <mtmorgan_at_fhcrc.org>
Date: Thu, 30 Aug 2007 05:54:16 -0700

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

-- 
Martin Morgan
Bioconductor / Computational Biology
http://bioconductor.org

______________________________________________
R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Received on Sat 01 Sep 2007 - 14:21:45 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Sat 01 Sep 2007 - 23:40:03 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.