[R] NAMESPACE vs internal.Rd

[Berwin A Turlach]

G'day Christophe,

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

> Hi the list,
> 
> When we use package.skeleton, it create some file in the man 
> directorie. - If we use package.skeleton with namespace=FALSE, it 
> create a file toto-internal.Rd
> - If we use package.skeleton with namespace=TRUE, it does not create 
> the file toto-internal.Rd
> 
> Why is that ?

My understanding from my reading of "Writing R Extension is" :

1) All functions/objects of a package that a user can call/see have to
be documented in order for the package passing "R CMD check" without
warnings/errors.

2) Users can see all functions/objects in packages without a namespace,
hence everything has to be documented.  For functions that you do not
want users to call directly, since they are help functions for the
"main" functions of your package", you can just create entries in
internal.Rd (or toto-internal.Rd) without writing a "complete" help
page for these functions.  "R CMD check" will accept this as
documentation.

3) In packages with a namespace, you decide which function/objects the
user can see by exporting them.  Everything not exported is supposed to
be internal to the package and should not be accessed directly by users
(though they can via :::).  Functions/objects that are not exported do
not need to be documented, hence no need for the toto-internal.Rd stub.

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