[Bioc-devel] runnable examples for internal function ?
Martin, Tiphaine
tiphaine.martin at kcl.ac.uk
Thu Oct 16 21:03:21 CEST 2014
Yep you guess well about my colleagues :) sorry.
Thank you for your advices.
Tiphaine
________________________________________
From: Hervé Pagès <hpages at fhcrc.org>
Sent: 16 October 2014 19:43
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/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.
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