'Re: [Bioc-devel] runnable examples for internal function ?'

[prev in list] [next in list] [prev in thread] [next in thread] 

List:       bioc-devel
Subject:    Re: [Bioc-devel] runnable examples for internal function ?
From:       Leonardo Collado Torres <lcollado () jhu ! edu>
Date:       2014-10-17 0:56:18
Message-ID: CAP8VEO6dsXXKVXKe1bDnp1NQaYt+JuTX14ZORN5Mzevf+9UUnw () mail ! gmail ! com
[Download RAW message or body]

On Thu, Oct 16, 2014 at 7:42 PM, Dan Tenenbaum <dtenenba@fhcrc.org> wrote:
> 
> 
> 
> ----- Original Message -----
> > From: "Hervé Pagès" <hpages@fhcrc.org>
> > To: "Tiphaine Martin" <tiphaine.martin@kcl.ac.uk>, "Michael Lawrence" \
> > <lawrence.michael@gene.com>, "Dan Tenenbaum" <dtenenba@fhcrc.org>
> > Cc: bioc-devel@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@fhcrc.org>
> > > Sent: 14 October 2014 03:02
> > > To: Martin, Tiphaine; Michael Lawrence; Dan Tenenbaum
> > > Cc: bioc-devel@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@gene.com>
> > > > Sent: 13 October 2014 21:52
> > > > To: Dan Tenenbaum
> > > > Cc: Martin, Tiphaine; bioc-devel@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@fhcrc.org<mailto:dtenenba@fhcrc.org>> wrote:
> > > > 
> > > > 
> > > > ----- Original Message -----
> > > > > From: "Tiphaine Martin"
> > > > > <tiphaine.martin@kcl.ac.uk<mailto:tiphaine.martin@kcl.ac.uk>>
> > > > > To: bioc-devel@r-project.org<mailto:bioc-devel@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@kcl.ac.uk<mailto:tiphaine.martin@kcl.ac.uk>
> > > > > Fax: +44 (0) 207 188 6761<tel:%2B44%20%280%29%20207%20188%206761>
> > > > > 
> > > > > [[alternative HTML version deleted]]
> > > > > 
> > > > > _______________________________________________
> > > > > Bioc-devel@r-project.org<mailto:Bioc-devel@r-project.org> mailing
> > > > > list
> > > > > https://stat.ethz.ch/mailman/listinfo/bioc-devel
> > > > > 
> > > > 
> > > > _______________________________________________
> > > > Bioc-devel@r-project.org<mailto:Bioc-devel@r-project.org> mailing
> > > > list
> > > > https://stat.ethz.ch/mailman/listinfo/bioc-devel
> > > > 
> > > > 
> > > > [[alternative HTML version deleted]]
> > > > 
> > > > _______________________________________________
> > > > Bioc-devel@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@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@fhcrc.org
> > Phone:  (206) 667-5791
> > Fax:    (206) 667-1319
> > 
> 
> _______________________________________________
> Bioc-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel

_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel

[prev in list] [next in list] [prev in thread] [next in thread] 