Axel,

R CMD check and CRAN's submission guidelines do not allow undocumented
*user facing* (i.e. exported) functions or objects in packages.

If you want the users of your package to be able calling the timestwo
function directly, it needs to be documented (and exported).

If, on the other hand, the timestwo function is only used internally by
other functions in your package, and there is no reason for the end user to
be calling it, it does not need to be exported or documented. The flip side
of this is that, as you saw, non-exported objects in packages are not
visible to the user when your package is loaded (::: not withstanding, but
there should "virtually never" be a situation where users using your
package normally should  need to be using :::).

You can't have an undocumented function in your package which users can
call directly from the commandline simply by typing its name at the prompt.
Or rather, you absolutely can, but CRAN will reject the package.

HTH,
~G


On Sat, Jan 25, 2014 at 11:47 AM, Axel Urbiz <axel.ur...@gmail.com> wrote:

> Thanks Dirk. Sorry...It's my misunderstanding about "export" in the
> NAMESPACE then. Essentially, as I understand it now, I should export all
> functions that are used in the package? Why would I not export a certain
> function?
>
> In the example above, say I wanted to avoid documenting the function
> "timestwo" in the foo package. Is there a way to do that? Otherwise in R
> CMD check foo, I get this "Undocumented code objects: ‘timestwo’".
>
> Thanks again for all your help!
> Axel.
>
>
> On Sat, Jan 25, 2014 at 8:32 PM, Dirk Eddelbuettel <e...@debian.org> wrote:
>
> >
> > On 25 January 2014 at 20:26, Axel Urbiz wrote:
> > | Dirk and Uwe, many thanks both for your responses. I'm still having the
> > same
> > | issue. Here's in more detail:
> > |
> > | As Dirk suggested, I've done the following:
> > |
> > | * I've created a package named {foo}.
> > |
> > | * {foo} only has one file named test.R which includes exactly the
> > following
> > | code:
> > |
> > |
> > | multiply <- function(x,y) x * y
> > |
> > | timestwo <- function(x) multiply(x, 2)
> > |
> > | * I've modified the NAMESPACE to include ONLY the following line:
> > |
> > | export(multiply)
> > |
> > | * I've successfully built and installed the foo package
> > |
> > | * Then in R I got this:
> > |
> > | > library(foo)
> > |
> > | > multiply(2,3)
> > |
> > | [1] 6
> > |
> > | > timestwo(2)
> > |
> > | Error: could not find function "timestwo"
> > |
> > | >
> > |
> > | * However, if in the NAMESPACE I write instead export(multiply,
> > timestwo), then
> > | I don't get the error above.
> >
> > That. Works. As. Designed. And. Documented.
> >
> >   Case 1)  You _export only multiply_. Hence timestwo is not found. Hint:
> >   learn about the difference between '::' and ':::' as well.
> >
> >   Case 2)  You _export both_. Both are found.
> >
> > No mystery.  What other effect do you expect export() to have?
> >
> > Dirk
> >
> > |
> > | * btw, here's my session info
> > |
> > | > sessionInfo()
> > |
> > | R Under development (unstable) (2014-01-17 r64821)
> > |
> > | Platform: x86_64-apple-darwin10.8.0 (64-bit)
> > |
> > | locale:
> > |
> > | [1] en_CA.UTF-8/en_CA.UTF-8/en_CA.UTF-8/C/en_CA.UTF-8/en_CA.UTF-8
> > |
> > | attached base packages:
> > |
> > | [1] stats     graphics  grDevices utils     datasets  methods   base
> > |
> > |
> > | other attached packages:
> > |
> > | [1] foo_1.0
> > |
> > |
> > | Thanks,
> > |
> > | Axel.
> > |
> > |
> > |
> > |
> > |
> > |
> > |
> > |
> > | On Sat, Jan 25, 2014 at 4:32 PM, Uwe Ligges <
> > lig...@statistik.tu-dortmund.de>
> > | wrote:
> > |
> > |
> > |
> > |     On 25.01.2014 14:53, Dirk Eddelbuettel wrote:
> > |
> > |
> > |         On 25 January 2014 at 14:38, Axel Urbiz wrote:
> > |         | Hello,
> > |         |
> > |         | I'm building a package. My code is stored in foo.R. This code
> > has two
> > |         | functions FUN1 and FUN2. FUN1 calls FUN2. FUN1 is listed in
> > export()
> > |         under
> > |         | the package NAMESPACE but NOT FUN2. After building the
> package
> > when I
> > |         call
> > |         | FUN1 is giving me an error that cannot find FUN2.
> > |
> > |         Then you are doing something wrong in building, or possibly
> > testing,
> > |         the package.
> > |
> > |
> > |
> > |     I guess you have FUN1 in your Workspace and using that rather than
> > the one
> > |     in your package.
> > |
> > |     Uwe Ligges
> > |
> > |
> > |
> > |
> > |         "Everything within" can see everything else.
> > |
> > |         | I solved this by adding FUN2 in the export() NAMESPACE.
> > However, what
> > |         is
> > |         | puzzling me is that I have other examples similar to the
> above
> > (i.e.,
> > |         one
> > |         | function calling another but only one exported) in the same
> > package
> > |         where I
> > |         | don't get the error message.
> > |         |
> > |         | Any idea of why that might be the case? My understanding is
> > that
> > |         export
> > |
> > |         We cannot tell without seeing the code.
> > |
> > |         I suggest you spend two minutes with package.skeleton(), create
> > an
> > |         empty
> > |         package, put something like these two functions in
> > |
> > |                   multiply <- function(x, k) x * k
> > |
> > |                   timestwo <- function(x) multiply(x, 2)
> > |
> > |         to convince yourself that timestwo() can in fact use
> multiply().
> > |
> > |         | only controls what is visible to the end user but functions
> not
> > |         listed in
> > |         | export() are still "usable" within the package.
> > |         |
> > |         | In this case, the reason I'd like to avoid to export FUN2 is
> > so I
> > |         don't
> > |         | have to add it in the package documentation.
> > |         |
> > |         |
> > |         | Any guidance is much appreciated.
> > |         |
> > |         | Regards,
> > |         | Axel.
> > |         |
> > |         |       [[alternative HTML version deleted]]
> > |         |
> > |         | ______________________________________________
> > |         | R-devel@r-project.org mailing list
> > |         | https://stat.ethz.ch/mailman/listinfo/r-devel
> > |
> > |
> > |
> >
> > --
> > Dirk Eddelbuettel | e...@debian.org | http://dirk.eddelbuettel.com
> >
>
>         [[alternative HTML version deleted]]
>
>
> ______________________________________________
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>


-- 
Gabriel Becker
Graduate Student
Statistics Department
University of California, Davis

        [[alternative HTML version deleted]]

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

Reply via email to