Skip to content
Prev 6461 / 21307 Next
Original Raw

[Bioc-devel] runnable examples for internal function ?

Hervé Pagès 
Hi Tiphaine,
On 10/13/2014 04:31 PM, Martin, Tiphaine wrote:
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.
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.
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.
Mandatory sections:

   \name{}
   \alias{}  # you can have more than 1 alias
   \title{}
   \description{}
   \usage{}
   \arguments{}
   \value{}
   \examples{}

Highly recommended sections:

   \seealso{}
   \details{}
Any function that is exported.

Hope this helps,
H.

  
    

      
      
    

  


  


  


  
  

    

  

    
      
    
    
Thread (10 messages)

  

  

    
            
        Martin, Tiphaine
        
        runnable examples for internal function ?
      
      Oct 13
    
    
      
            
        Dan Tenenbaum
        
        runnable examples for internal function ?
      
      Oct 13
    
    
      
            
        Michael Lawrence
        
        runnable examples for internal function ?
      
      Oct 13
    
    
      
            
        Martin, Tiphaine
        
        runnable examples for internal function ?
      
      Oct 13
    
    
      
            
        Hervé Pagès
        
        runnable examples for internal function ?
      
      Oct 13
    
    
      
            
        Martin, Tiphaine
        
        runnable examples for internal function ?
      
      Oct 15
    
    
      
            
        Hervé Pagès
        
        runnable examples for internal function ?
      
      Oct 16
    
    
      
            
        Martin, Tiphaine
        
        runnable examples for internal function ?
      
      Oct 16
    
    
      
            
        Dan Tenenbaum
        
        runnable examples for internal function ?
      
      Oct 16
    
    
      
            
        Leonardo Collado Torres
        
        runnable examples for internal function ?
      
      Oct 16