[R] NAMESPACE vs internal.Rd

[cgenolin at u-paris10.fr]

Thanks, Berwin,

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 ?
- some fonction will be "accessible" (regular function)
- some function will be "hidden" (function starting with .)
- some function will be "forbiden" (function not in namespace)

I am just asking as a beginner that try to understand how pacakge 
works, I do not say that it is a good way to do...

Christophe

> 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
>