G'day Christophe, On Wed, 16 Jul 2008 16:11:15 +0200 [EMAIL PROTECTED] 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: [EMAIL PROTECTED] Singapore 117546 http://www.stat.nus.edu.sg/~statba ______________________________________________ R-help@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.