On 8/30/07, James W. MacDonald <[EMAIL PROTECTED]> 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 <[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 > ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
