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

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
<mailto: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 <mailto: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 <mailto: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 <mailto:plijnzaad at jabber.org> ,
                philip.lijnzaad at gmail.com <mailto:philip.lijnzaad at gmail.com>
                P.O. Box 85060, 3508 AB Utrecht
                (Universiteitsweg 100, 3584 CG Utrecht)
                The Netherlands
                tel: +31 (0)8875 68464 <tel:%2B31%20%280%298875%2068464>

                ------------------------------__------------------------------
                ------------------

                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}}