R devel - Aug 2012 - how to keep the documents of private functions private

First time posting on this forum.

The short version of the question is how to keep the documents of private
(unexported) functions private. It seems that the documents of the private
functions will be compiled into the user manual even if the corresponding
functions are not exported. Is there a solution to this? I want to have
documents for these functions for my own use, but I don’t want to release them
to distract end users.

To provide some background, a more general question is how to manage unexported
(private) functions in an R package. I need to call them during the developing
phase or even after the package is released (e.g., for debugging purpose or they
may be needed by new functions), but I don’t want to export them (I’d like to
keep the number of exported (public) functions to a minimum and present the
users with only the functions that they need to know.)

I know I can call private functions by packagename:::fcn(), but that seems a
little bit tedious.

A solution I came up with is to prepare two NAMESPACE files and switch between
them. When releasing the codes, use the thin version; when developing the
package, use the version that export all functions. That works except if I have
documents (Rd files) for the private functions, they will be compiled to the
user manual even if the corresponding functions are not exported. Is there a
solution around this? (I think I can keep two separate man folders and switch
between them, but that seems a little bit tedious).

Thanks.

Yanming



	[[alternative HTML version deleted]]

On 12-08-24 11:56 AM, Yanming Di wrote:
> First time posting on this forum.
>
> The short version of the question is how to keep the documents of private
(unexported) functions private. It seems that the documents of the private
functions will be compiled into the user manual even if the corresponding
functions are not exported. Is there a solution to this? I want to have
documents for these functions for my own use, but I don???t want to release them
to distract end users.
You can't easily do that.  Some base packages have a topic like 
?"grid-internal" where internal documentation is collected, but it is 
visible to users.
> To provide some background, a more general question is how to manage
unexported (private) functions in an R package. I need to call them during the
developing phase or even after the package is released (e.g., for debugging
purpose or they may be needed by new functions), but I don???t want to export
them (I???d like to keep the number of exported (public) functions to a minimum
and present the users with only the functions that they need to know.)
>
> I know I can call private functions by packagename:::fcn(), but that seems
a little bit tedious.
You could also attach the environment of an exported function (e.g. 
attach(environment(grid::unit)), to put the whole internal environment 
on the search list.  But I usually use the ::: notation.

Duncan Murdoch

>
> A solution I came up with is to prepare two NAMESPACE files and switch
between them. When releasing the codes, use the thin version; when developing
the package, use the version that export all functions. That works except if I
have documents (Rd files) for the private functions, they will be compiled to
the user manual even if the corresponding functions are not exported. Is there a
solution around this? (I think I can keep two separate man folders and switch
between them, but that seems a little bit tedious).
>
> Thanks.
>
> Yanming
>
>
>
> 	[[alternative HTML version deleted]]
>
>
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

> To provide some background, a more general question is how to manage
unexported (private) functions in an R package. I need to call them during the
developing phase or even after the package is released (e.g., for debugging
purpose or they may be needed by new functions), but I don?t want to export them
(I?d like to keep the number of exported (public) functions to a minimum and
present the users with only the functions that they need to know.)
The devtools package allows you to do load_all("path/to/package"),
which simulates installing the package and then loading it (but is
much faster, at the cost of being a somewhat imperfect simulation).
Because working with unexported functions is so useful during
development, it makes all them all available.  (And the development
version allows you to choose whether or not you want them available)

I typically generate documentation with inline source comments (using
roxygen2). If I want them to be turned into Rd files and accessible to
the user I use the roxygen comments (#'). If I just want them to be
available to me (and other developers), I just use # - then they're
available in the source, but not in the man/ directory.

Hadley

-- 
Assistant Professor
Department of Statistics / Rice University
http://had.co.nz/