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 <[EMAIL PROTECTED]> 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@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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
