[R] NAMESPACE vs internal.Rd

[Berwin A Turlach]

G'day Christophe,

On Wed, 16 Jul 2008 16:11:15 +0200
cgenolin at u-paris10.fr wrote:

> So the main idea is - With NAMESPACE, you do not document the 
> "not-for-user" because they don't have to be documented
> - Witout NAMESPACE, you document the "not-for-user" with a 
> toto-internal.Rd that say "not for user"
> 
> That's clear.
> 
> Is it stupid to consider to use both technique at the same time ?

As far as I know, R will not complain if you write documentation for
objects that you do not have to document.  "R CMD check" will complain
if an object accessible to a user of the package is not documented.

A quick perusal of the packages installed on my machine shows that
there are several packages that have a namesspace and a XXXX-internal
file, e.g. the MASS package (from the VR bundle) and the sm package.

But both these packages existed before the namespace mechanism was
introduced.  So the MASS-internal.Rd and sm-internal.Rd may be
remainders from the time before namespaces were introduced.  

You would have to ask the maintainer(s) of such packages why they use a
namespace and a XXXX-internal.Rd file.  I can see no reason but a
historical one that the XXXX-internal.Rd file stems from the time before
namespaces and was not deleted after their introduction (I know that I
wouldn't delete such a file if it weren't necessary).

> - some fonction will be "accessible" (regular function)
> - some function will be "hidden" (function starting with .)
> - some function will be "forbiden" (function not in namespace)

We are actually talking objects (everything in R is an object) which
could be anything, a function, a data frame or ...

But if you want to keep the discussion restricted to functions then I
would want to point out that functions that start with a . are only
hidden from the ls() function and that this has nothing to do with a
namespace.

According to my understanding, if your package has a namespace, then
everything that you do not export explicitly is not visible to users of
your package.  The "Writing R Extensions" manual has an example for an
exportPattern() directive that exports all variables that do not start
with a period, but that would export everything else.  I guess writing
a regular expression that says "export everything that does not start
with a dot but do not export foo and bar" would be not trivial to write
(at least not for me).

And your distinction between "hidden" and "forbidden" functions is
spurious because either function could be accessed via the ":::"
operator if the user knows that it is in the package (though not
exported). 

Thus, if you use a namespace, then all the objects that you export are
visible to the users of the package;  all other objects are not visible
(but can be accessed via ":::").  Objects that are not visible do not
need to be documented (for "R CMD check" to succeed), but it is no
error to document them.  Objects that are visible to the users of the
package have to be documented.

HTH (and HTIC).

Cheers,

	Berwin

=========================== Full address =============================
Berwin A Turlach                            Tel.: +65 6516 4416 (secr)
Dept of Statistics and Applied Probability        +65 6516 6650 (self)
Faculty of Science                          FAX : +65 6872 3919       
National University of Singapore     
6 Science Drive 2, Blk S16, Level 7          e-mail: statba at nus.edu.sg
Singapore 117546                    http://www.stat.nus.edu.sg/~statba