----- Original Message ----- > From: "Hervé Pagès" <hpa...@fhcrc.org> > To: "Tiphaine Martin" <tiphaine.mar...@kcl.ac.uk>, "Michael Lawrence" > <lawrence.mich...@gene.com>, "Dan Tenenbaum" > <dtene...@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. > 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 <hpa...@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.mich...@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 > >> <dtene...@fhcrc.org<mailto:dtene...@fhcrc.org>> wrote: > >> > >> > >> ----- Original Message ----- > >>> From: "Tiphaine Martin" > >>> <tiphaine.mar...@kcl.ac.uk<mailto:tiphaine.mar...@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.mar...@kcl.ac.uk<mailto:tiphaine.mar...@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: hpa...@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: hpa...@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
