Skip to content

[R-pkg-devel] Inquiry

8 messages · teimouri m@iii@g oii @ut@@c@ir, Andrew Simmons, Rolf Turner +3 more

Original
teimouri m@iii@g oii @ut@@c@ir
# 
?Hi there,
I am writing to aks your help for an issuue arising when I am writing my R package using R studio 1.2.1335 as follows.
``checking for missing documentation entries ... WARNING
Undocumented code objects:
  'r2'
All user-level objects in a package should have documentation entries."
The function r2.r is among  .r   files within R folder of my package. 
I am not interested to present "r2" in the R topics documented: as a part of first page of built pdf help file of my package.
I appreciate highly if you could help me to solve this issue.
Andrew Simmons
# 
This issue isn't related to RStudio.

The issue is that you're exporting an object without providing any
documentation for it. It sounds like you don't want to export it, so you
need to go to your NAMESPACE file and remove the part was export(r2). If
you do want to export it, then you need to document it, there's no way
around that. The documentation doesn't need to be very detailed.
On Mon., Sep. 26, 2022, 20:01 , <teimouri at aut.ac.ir> wrote:

            

      
      
      
    

        

      
      
    

        

  
  


  


      

    

    

      
      

        


  

        

      Rolf Turner
    

    

      
      #
    

  


  

      
On Mon, 26 Sep 2022 20:07:28 -0400

        
Andrew Simmons <akwsimmo at gmail.com> wrote:

        

            

      
      
      
    

        
My understanding is that functions, that are not meant to be called
directly by users, should be documented in a file named
<pkgnm>-internal.Rd.  It should have a structure something like:

            

      
      
      
    

        
Then if someone types, e.g., "help(clyde)" they get the processed
form of the forgoing *.Rd file displayed, and are thereby told that
they probably should not mess with clyde().

cheers,

Rolf Turner

P.S. I always export everything.

R. T.

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Georgi Boshnakov
    

    

      
      #
    

  


  

          

      
      
      
    

        
This is one option, convenient in the use-case of the question. But why export a function that you actively don't want the users to know about? There are cases when this is needed or convenient but particularly with 'roxygen2' it is just about deleting an '@export' line.
 
Just for completeness, non-exported functions can be documented as any other functions. Adding

\keyword{internal}

will prevent them from appearing in manuals (but still accessible via '?'). Stating clearly that such functions are internal is also sensible. 


Georgi Boshnakov

-----Original Message-----
From: R-package-devel <r-package-devel-bounces at r-project.org> On Behalf Of Rolf Turner
Sent: 27 September 2022 02:38
To: Andrew Simmons <akwsimmo at gmail.com>
Cc: List r-package-devel <r-package-devel at r-project.org>
Subject: Re: [R-pkg-devel] Inquiry


On Mon, 26 Sep 2022 20:07:28 -0400

        
Andrew Simmons <akwsimmo at gmail.com> wrote:

        

            

      
      
      
    

        
My understanding is that functions, that are not meant to be called directly by users, should be documented in a file named <pkgnm>-internal.Rd.  It should have a structure something like:

            

      
      
      
    

        
Then if someone types, e.g., "help(clyde)" they get the processed form of the forgoing *.Rd file displayed, and are thereby told that they probably should not mess with clyde().

cheers,

Rolf Turner

P.S. I always export everything.

R. T.

--
Honorary Research Fellow
Department of Statistics
University of Auckland
Phone: +64-9-373-7599 ext. 88276

______________________________________________
R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel

  
  


  


      

    

    

      
      

        


  

        

      Rolf Turner
    

    

      
      #
    

  


  

      
On Tue, 27 Sep 2022 07:43:03 +0000

        
Georgi Boshnakov <georgi.boshnakov at manchester.ac.uk> wrote:

        

            

      
      
      
    

        
<SNIP>

Why would you not want users to know about functions?  This strikes me
as being overly authoritarian. Of course, to export or not to export
is the choice of the package author.  It is also sensible to try to
protect users from shooting themselves in the foot.  However if they
really want to shoot themselves in the foot, that's their call.

Anyway, users can always get at non-exported functions using ":::".

cheers,

Rolf Turner

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Jeff Newmiller
    

    

      
      #
    

  


  

      
If you haven't settled on exactly which approach you want to use in accomplishing the main goals of your exported package functions, then hiding the gory details can make it easier to tell people later to sod off when you decide those gory details functions should act different or use different function signatures.

Anyone regularly using ::: earns the lack of reproducibility they get.

        
On September 27, 2022 6:37:28 PM PDT, Rolf Turner <r.turner at auckland.ac.nz> wrote:

            

      
      
      
    

        

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Duncan Murdoch
    

    

      
      #
    

  


  

      
On 27/09/2022 9:37 p.m., Rolf Turner wrote:

            

      
      
      
    

        
There are (at least) two kinds of users.  The more common kind writes 
scripts that use your package.  I think your argument is valid for that 
group, though many of them are never going to read your warning about 
functions being intended for internal use.

However, some users are package writers.  Once their package is on CRAN, 
it can be really inconvenient for you to change the behaviour of 
internal functions that they use, because CRAN will object if your 
change breaks their tests.  That makes it harder to write those internal 
functions, because you have to get them "right" the first time, or 
support the bad behaviour if someone relied on it.

Duncan Murdoch

  
  


  


      

    

    

      
      

        


  

        

      Rolf Turner
    

    

      
      #
    

  


  

      
On Wed, 28 Sep 2022 05:19:06 -0400

        
Duncan Murdoch <murdoch.duncan at gmail.com> wrote:

        
<SNIP>

            

      
      
      
    

        
Surely package writers should not write code that uses internal
functions, irrespective of whether these functions are exported.
I don't think that I ever have.  (That last could be wishful thinking I
guess.)

Not exporting makes it harder for package writers to know about the
*existence* of such functions, but it's not impossible (or even really
difficult) for a package-writer-type to find out about them.

The write can always then make a copy of the code in their own package,
which eliminates the problem with dependencies.

Anyway, does everybody 'get them "right" the first time'? :-)

cheers,

Rolf