R devel - Aug 2007 - suggesting \alias* for Rd files (in particular for S4 method documentation)

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

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