[Bioc-devel] Documentation of GenomicRanges::follow etc. very hard to find

[James W. MacDonald]

I agree with Michael. In my opinion, the help pages for S4 methods are
painfully obscure, and expecting anybody (let alone a newbie) to figure out
that they need to do something like method?"follow,GenomicRanges,
GenomicRanges" in order to get the help page for a method is a high hurdle
indeed.

In fact, I can't remember the last time I actually tried to find a help
page for an S4 method. I much prefer traversing the methods tree using
showMethods(), and tracking down the method that will dispatch on whatever
object I have in hand, rather than trying to figure out what incredibly
unintuitive combination of names, quotes, question marks (and the required
order thereof) is required to get the help page.

Best,

Jim



On Wed, Feb 18, 2015 at 9:10 AM, Michael Lawrence <lawrence.michael at gene.com
> wrote:

> I guess this is really an argument for having _all_ method man pages be
> aliased with the symbol of the generic. I wonder if R should just be made
> smarter and bring up a menu whenever help is requested on a generic,
> listing all of the available methods, with the default method as the
> default selection.
>
> On Wed, Feb 18, 2015 at 8:38 AM, Philip Lijnzaad <p.lijnzaad at umcutrecht.nl
> >
> wrote:
>
> > On 02/18/2015 05:13 PM, Martin Morgan wrote:
> >
> >> On 02/18/2015 08:05 AM, Philip Lijnzaad wrote:
> >>
> >>>
> >>>     Dear all,
> >>>     looking up the documentation on functions like follow() and
> >>> precede() is
> >>>     very hard, since they are only documented under the topic
> >>> "nearest-methods",
> >>>     which currently (GenomicRanges package 1.18.4) can only be found
> >>> using the
> >>>     ?? operator (and having found the name of the topic, most newbies
> >>> are still
> >>>
> >>
> >> FWIW
> >>
> >> > method?"follow<tab>
> >>
> >> shows
> >>
> >> ANY,SummarizedExperiment
> >> GenomicRanges,GenomicRanges
> >> GenomicRanges,missing
> >> SummarizedExperiment,ANY
> >> SummarizedExperiment,SummarizedExperiment
> >> Ranges,RangesORmissing
> >>
> >> suggesting, e.g.,
> >>
> >> > method?"follow,GenomicRanges,GenomicRanges"
> >>
> >>
> > Hi Martin, thanks for the feedback. To be honest, your solution involves
> > more typing, and is not newbie-friendly since the
> > newbie doesn't now anything about "methods". S/he simply types ?follow
> and
> > gets back an answer (from the IRanges docu),
> > and subsequently thing "oh well, follow() doesn't know about strands, and
> > then gets stuck). My request is simply to add the plain \alias{}es, i.e.
> > just like we have for findOverlaps and the methods described in
> > inter-range-methods.Rd. Or what would be the argument against that?
> >
> > Cheers,
> >
> >
> > Philip
> >
> > --
> > Philip Lijnzaad, PhD
> > Molecular Cancer Research
> > University Medical Center (UMC), Utrecht
> > Stratenum room 2.211
> > IM: plijnzaad at jabber.org , philip.lijnzaad at gmail.com
> > P.O. Box 85060, 3508 AB Utrecht
> > (Universiteitsweg 100, 3584 CG Utrecht)
> > The Netherlands
> > tel: +31 (0)8875 68464
> >
> > ------------------------------------------------------------
> > ------------------
> >
> > De informatie opgenomen in dit bericht kan vertrouwelijk zijn en is
> > uitsluitend bestemd voor de geadresseerde. Indien u dit bericht onterecht
> > ontvangt, wordt u verzocht de inhoud niet te gebruiken en de afzender
> > direct
> > te informeren door het bericht te retourneren. Het Universitair Medisch
> > Centrum Utrecht is een publiekrechtelijke rechtspersoon in de zin van de
> > W.H.W.
> > (Wet Hoger Onderwijs en Wetenschappelijk Onderzoek) en staat
> geregistreerd
> > bij
> > de Kamer van Koophandel voor Midden-Nederland onder nr. 30244197.
> >
> > Denk s.v.p aan het milieu voor u deze e-mail afdrukt.
> >
> > ------------------------------------------------------------
> > ------------------
> >
> > This message may contain confidential information and ...{{dropped:11}}
>
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>



-- 
James W. MacDonald, M.S.
Biostatistician
University of Washington
Environmental and Occupational Health Sciences
4225 Roosevelt Way NE, # 100
Seattle WA 98105-6099

	[[alternative HTML version deleted]]