[Bioc-devel] runnable examples for internal function ?
Dan Tenenbaum
dtenenba at fhcrc.org
Fri Oct 17 01:42:21 CEST 2014
----- 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.
> 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
>
More information about the Bioc-devel
mailing list