[Bioc-devel] runnable examples for internal function ?

Leonardo Collado Torres lcollado at jhu.edu
Fri Oct 17 02:56:18 CEST 2014 

On Thu, Oct 16, 2014 at 7:42 PM, Dan Tenenbaum <dtenenba at fhcrc.org> wrote:
>
>
>
> ----- Original Message -----
> > From: "Hervé Pagès" <hpages at fhcrc.org>
> > To: "Tiphaine Martin" <tiphaine.martin at kcl.ac.uk>, "Michael Lawrence" <lawrence.michael at gene.com>, "Dan Tenenbaum"
> > <dtenenba at fhcrc.org>
> > Cc: bioc-devel at r-project.org
> > Sent: Thursday, October 16, 2014 11:43:32 AM
> > Subject: Re: [Bioc-devel] runnable examples for internal function ?
> >
> > Hi Tiphaine,
> >
> > On 10/15/2014 06:30 AM, Martin, Tiphaine wrote:
> > >
> > > Hi Herve,
> > >
> > > Thank you for your email. very useful.
> > > But I updated my NAMESPACE in order to list only functions that I
> > > want to export.
> > > Even if I did that and if in addition, I keep different man files
> > > for functions that I do not want to export, I have this error
> > > message.
> > > But if I removed them, I don't have error messages.
> > > I kept different man files for functions that I do not want to
> > > export to help my colleagues. It seems that currently, it is not
> > > recommended in Bioconductor.
> >
> > By "colleagues" I guess you mean "co-developers", not "users" of
> > your package right?
> >
> > Yes it seems reasonable to expect 'R CMD BiocCheck' to only check
> > \value and \example for man pages that document exported things.
> > We should fix that.
> >
>
> I am looking at the build report for your latest upload:
>
> http://bioconductor.org/spb_reports/coMET_0.99.2_buildreport_20141016031739.html#oaxaca_check_anchor
>
> I do not see that BiocCheck is complaining about this.
>
> Are you running BiocCheck on your own machine against a newer version of the package? If so, can you send me the package (off-list)?
>
> If BiocCheck really is doing the wrong thing, I need to be able to reproduce the problem in order to fix it. So I would appreciate it if you can send me a package that causes this problem.
>
> Thanks,
> Dan
>
>
>
>
> > Note that it's questionable whether it's a good idea or not to keep
> > around man pages for non exported things. IMO it's better to document
> > internal helpers using in-source comments. And since you already
> > have those in-source comments in place anyway (because you're
> > using roxygen2), all you need to do is find a way to block
> > roxygen2 from generating the man pages for these internal helpers.



Just use a dot at the beginning of the name for your internal
function. Then `devtools` will ignore them. For example, using so with
my package skips the 5 internal functions that have roxygen2 in-source
documentation but that are not exported.

> library('devtools')
> document('derfinder')
Updating derfinder documentation
Loading derfinder
Skipping invalid path:  .getSegmentsRle.Rd
Skipping invalid path:  .clusterMakerRle.Rd
Skipping invalid path:  .advanced_argument.Rd
Skipping invalid path:  .define_cluster.Rd
Skipping invalid path:  .runFunFormal.Rd

> packageVersion('devtools')
[1] ‘1.6.1’
> packageVersion('roxygen2')
[1] ‘4.0.2’

Cheers,
Leo


>
> > Co-developers of your package will still be able to see useful
> > information and that information will be placed where developers
> > expect it to be: in the source code itself.
> >
> > My 2 cents.
> >
> > Cheers,
> > H.
> >
> > >
> > > thank you for your help,
> > >
> > > Tiphaine
> > > ________________________________________
> > > From: Hervé Pagès <hpages at fhcrc.org>
> > > Sent: 14 October 2014 03:02
> > > To: Martin, Tiphaine; Michael Lawrence; Dan Tenenbaum
> > > Cc: bioc-devel at r-project.org
> > > Subject: Re: [Bioc-devel] runnable examples for internal function ?
> > >
> > > Hi Tiphaine,
> > >
> > > On 10/13/2014 04:31 PM, Martin, Tiphaine wrote:
> > >> Hi,
> > >>
> > >>
> > >> I wrote a list of functions used in my package called coMET. I
> > >> decided with my colleagues to try to publish it in Bioconductor.
> > >> Currently, it has not been yet submitted to bioconductor because
> > >> I would like to be sure that it satisfies all your guidelines.
> > >> A list of functions is useful only internally. I saw that there
> > >> are two methods to remove the function from the package index and
> > >> to disable some of their automated tests: the first method is to
> > >> put a dot as first letter, the second method is to put the
> > >> "internal" keyword
> > >> (http://cran.r-project.org/web/packages/roxygen2/vignettes/rdkeywords.html).
> > >
> > > That link is to the documentation of the roxygen2 package. Are you
> > > using roxygen2 to develop your package? You didn't say so.
> > > You say that "you saw that prefixing the function name with a dot
> > > or putting the 'internal' keyword in the man page will 'remove the
> > > function from the package index and disable some of its automated
> > > tests'". I guess that's something you saw in the roxygen2
> > > documentation
> > > right? I don't use roxygene2 myself so I don't know what's the
> > > roxygen2
> > > way to control what's exposed or not to the user. However I know
> > > many
> > > BioC developers use it for their package so maybe they'll be able
> > > to
> > > provide some good advice here.
> > >
> > > Keep in mind that using a tool like roxygen2 adds an extra layer of
> > > convenience when developing your package but, unfortunately, it
> > > doesn't
> > > completely exempt you from learning and understanding some basic
> > > concepts like NAMESPACE, man pages aliases, keywords, etc...
> > > The ultimate reference for these things is still the "Writing R
> > > Extensions" manual:
> > >
> > >     http://cran.r-project.org/doc/manuals/r-release/R-exts.html
> > >
> > > So, and FWIW, below I'll describe quickly how you need to proceed
> > > when
> > > you don't use a fancy tool like roxygen2 to automatically generate
> > > the NAMESPACE and man pages in your package:
> > >
> > > 1) The real true way to not expose a function to the user is to not
> > >      export it. What one exports from a package is controlled via
> > >      the NAMESPACE file. So first you need to learn about how to
> > >      use
> > >      the NAMESPACE file to control exactly what you want to expose
> > >      to
> > >      the user. See "Writing R Extensions" manual for the details.
> > >
> > > 2) Every symbol that is exported needs to be documented, that is,
> > > there
> > >      must be a man page with an alias for this symbol. And of
> > >      course
> > >      opening the man page at the R prompt with ?<symbol> should
> > >      display
> > >      useful information about that symbol.
> > >      'R CMD check' is the tool that will check that every exported
> > >      symbol is documented. It will also perform many checks on the
> > >      man pages to make sure that they are formatted properly.
> > >
> > > 3) As Dan said previously, any function that is exported also needs
> > >      to have runnable examples and a \value section in its man
> > >      page.
> > >      Note that this is a Bioconductor requirement, 'R CMD check'
> > >      doesn't check that. 'R CMD BiocCheck' is the tool that will
> > >      perform this check and any other Bioconductor specific check.
> > >
> > >> I decided to use the second method to reduce to rewrite now all my
> > >> package.
> > >
> > > Note that, for "plain package development" (i.e. without using a
> > > a fancy tool like roxygen2), using the "internal" keyword in a man
> > > page has no effect on whether the function is exported or not.
> > >
> > >>
> > >>
> > >> When I run the new version of BiocCheck Version 1.1.18 with empty
> > >> \value and \example sections for function with "internal" keyword
> > >> , I have error message asking to add no-empty runnable examples.
> > >>
> > >> When I run the new version of BiocCheck Version 1.1.18 without
> > >> \value and \example sections for function with "internal" keyword
> > >> , I have error message asking to add non-empty \value sections.
> > >>
> > >> with BiocCheck, version 1.0.2, I had a message for functions with
> > >> "internal" keyword such as "
> > >> Checking exported objects have runnable examples...
> > >> * CONSIDER: Adding runnable examples to the following man pages
> > >> which document exported objects:"
> > >>
> > >> I would like to know if I made a mistake to use internal keyword
> > >> for this type of functions. What do I need to do ?
> > >
> > > These changes in the output of BiocCheck are due to changes in
> > > BiocCheck itself. In particular, the check on \value section was
> > > added recently, and the check on the runnable examples was changed
> > > recently from RECOMMENDED to REQUIRED.
> > >
> > >>
> > >> Which sections are mandatory in manual file
> > >
> > > Mandatory sections:
> > >
> > >     \name{}
> > >     \alias{}  # you can have more than 1 alias
> > >     \title{}
> > >     \description{}
> > >     \usage{}
> > >     \arguments{}
> > >     \value{}
> > >     \examples{}
> > >
> > > Highly recommended sections:
> > >
> > >     \seealso{}
> > >     \details{}
> > >
> > >> and for which function I need to do a manual file ?
> > >
> > > Any function that is exported.
> > >
> > > Hope this helps,
> > > H.
> > >
> > >>
> > >>
> > >> Regards,
> > >> Tiphaine
> > >>
> > >>
> > >> ________________________________
> > >> From: Michael Lawrence <lawrence.michael at gene.com>
> > >> Sent: 13 October 2014 21:52
> > >> To: Dan Tenenbaum
> > >> Cc: Martin, Tiphaine; bioc-devel at r-project.org
> > >> Subject: Re: [Bioc-devel] runnable examples for internal function
> > >> ?
> > >>
> > >> It would be nice to know the use case of the internal keyword
> > >> here. I've use it to avoid listing functions in the index (RGtk2
> > >> has thousands of functions). But in general, it's not a good idea
> > >> to be exporting things that are truly internal. Perhaps internal
> > >> methods on exported generics, but even then, it's probably best
> > >> to keep the aliases with the generic, or something.
> > >>
> > >>
> > >> On Mon, Oct 13, 2014 at 1:33 PM, Dan Tenenbaum
> > >> <dtenenba at fhcrc.org<mailto:dtenenba at fhcrc.org>> wrote:
> > >>
> > >>
> > >> ----- Original Message -----
> > >>> From: "Tiphaine Martin"
> > >>> <tiphaine.martin at kcl.ac.uk<mailto:tiphaine.martin at kcl.ac.uk>>
> > >>> To: bioc-devel at r-project.org<mailto:bioc-devel at r-project.org>
> > >>> Sent: Monday, October 13, 2014 1:29:08 PM
> > >>> Subject: [Bioc-devel] runnable examples for internal function ?
> > >>>
> > >>> Hi,
> > >>>
> > >>>
> > >>> I would like to know if I need to add a runnable example for each
> > >>> function that has keyword either internal or not.
> > >>>
> > >>
> > >> I don't know what you mean by this, but maybe I should.
> > >>
> > >>>
> > >>> I ask that because with BiocCheck, version 1.0.2, I had a message
> > >>> for
> > >>> function with keyword "internal" such as "
> > >>>
> > >>> Checking exported objects have runnable examples...
> > >>>       * CONSIDER: Adding runnable examples to the following man
> > >>>       pages
> > >>>         which document exported objects:"
> > >>>
> > >>
> > >> If the function is exported, it must have a runnable example.
> > >>
> > >>
> > >>> and now, I have an error message with BiocCheck, version 1.1.18
> > >>>
> > >>> * Checking exported objects have runnable examples...
> > >>> Error in if (line == "## No test: " || insideDontTest || line ==
> > >>> "##
> > >>> End(No test)") { :
> > >>>     missing value where TRUE/FALSE needed
> > >>> Calls: <Anonymous> ... checkExportsAreDocumented ->
> > >>> doesManPageHaveRunnableExample -> removeDontTest
> > >>> Execution halted
> > >>>
> > >>
> > >> Can you file an issue at
> > >> https://github.com/Bioconductor/BiocCheck/issues and include the
> > >> name of the package?
> > >> I will get to it as soon as I can.
> > >>
> > >> Dan
> > >>
> > >>
> > >>>
> > >>> Regards,
> > >>>
> > >>> Tiphaine
> > >>>
> > >>>
> > >>>
> > >>> ----------------------------
> > >>> Tiphaine Martin
> > >>> PhD Research Student | King's College
> > >>> The Department of Twin Research & Genetic Epidemiology | Genetics
> > >>> &
> > >>> Molecular Medicine Division
> > >>> St Thomas' Hospital
> > >>> 4th Floor, Block D, South Wing
> > >>> SE1 7EH, London
> > >>> United Kingdom
> > >>>
> > >>> email :
> > >>> tiphaine.martin at kcl.ac.uk<mailto:tiphaine.martin at kcl.ac.uk>
> > >>> Fax: +44 (0) 207 188 6761<tel:%2B44%20%280%29%20207%20188%206761>
> > >>>
> > >>>         [[alternative HTML version deleted]]
> > >>>
> > >>> _______________________________________________
> > >>> Bioc-devel at r-project.org<mailto:Bioc-devel at r-project.org> mailing
> > >>> list
> > >>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
> > >>>
> > >>
> > >> _______________________________________________
> > >> Bioc-devel at r-project.org<mailto:Bioc-devel at r-project.org> mailing
> > >> list
> > >> https://stat.ethz.ch/mailman/listinfo/bioc-devel
> > >>
> > >>
> > >>        [[alternative HTML version deleted]]
> > >>
> > >> _______________________________________________
> > >> 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 fhcrc.org
> > > Phone:  (206) 667-5791
> > > Fax:    (206) 667-1319
> > >
> >
> > --
> > 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 fhcrc.org
> > Phone:  (206) 667-5791
> > Fax:    (206) 667-1319
> >
>
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel

More information about the Bioc-devel mailing list