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

Wed Feb 18 20:31:42 CET 2015

What Michael suggests is obviously the way forward.

To be clear: what Herve is doing is somewhat simple though: if a man page
is for a specific method, it should also contain
  \alias{$GENERIC}

Kasper

On Wed, Feb 18, 2015 at 2:12 PM, Michael Lawrence <lawrence.michael at gene.com
> wrote:

> Great. I was just wondering whether we could make the job of the developer
> easier by having R find the methods, instead of needing to add aliases to
> every method man page.
>
> On Wed, Feb 18, 2015 at 10:50 AM, Hervé Pagès <hpages at fredhutch.org>
> wrote:
>
> > Hi,
> >
> > Philip makes a very good point. This is exactly the reason why,
> > a few months ago, I started to alias method man pages with the
> > symbol of the generic. For example I've done it for findOverlaps
> > and all the intra- and inter- range methods (shift, resize, flank,
> > range, reduce, etc...). So after loading the GenomicRanges
> > package, if you do ?reduce, you are presented the list of man pages
> > that document a "reduce" method (there is one in IRanges and one in
> > GenomicRanges) and you can select the one you want. If you do
> > ?findOverlaps after loading the GenomicAlignments package, you get
> > to choose between 3 man pages.
> >
> > I've not done this in a systematic way yet but this is the long
> > term plan. In the mean time, I just did it for the "precede", "follow",
> > "nearest", "distance", and "distanceToNearest" in GenomicRanges.
> > This is in GenomicRanges 1.19.38 (BioC devel). More will follow...
> >
> > Cheers,
> > H.
> >
> >
> > On 02/18/2015 09:35 AM, James W. MacDonald wrote:
> >
> >> 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
> >>>
> >>>
> >>
> >>
> >>
> > --
> > Hervé Pagès
> >
> > Program in Computational Biology
> > Division of Public Health Sciences
> > Fred Hutchinson Cancer Research Center
> > 1100 Fairview Ave. N, M1-B514
> > P.O. Box 19024
> > Seattle, WA 98109-1024
> >
> > E-mail: hpages at fredhutch.org
> > Phone:  (206) 667-5791
> > Fax:    (206) 667-1319
> >
>
>         [[alternative HTML version deleted]]
>
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>

	[[alternative HTML version deleted]]