R devel - Jul 2006 - Documentation: add a bit note (PR#9066)

Full_Name: Feiming Chen
Version: 2.0.0
OS: Unix
Submission from: (NULL) (216.52.132.10)


Just a note to clarify the document "Writing R Extensions". 

As a beginner, I was a little confused about this paragraph:

Section 1.1.4 Package subdirectories, page 6, the paragraph in the
middle:  "The 'man' subdirectory ... Note that all user-level
objects in a
package should be documented; if a package pkg contains user-level objects which
are for 'internal' only, it should provide a file pkg-internal.Rd which
documents all such objects, and clearly states that these are not meant to be
called by the user. See e.g. the sources for package grid in the R distribution
for an example."

I just try to skip writing Rd 
files for numerous small R functions (for "internal" use, that is,
called
by other functions).  I thought the only way is to put them in
pkg-internal.Rd until I read about NAMESPACE in section 1.6. 
I find out I just need to export those R functions that are needed by
the user and then "R CMD check" won't complain not seeing the docs
for
all other functions, along with some error messages. 

So maybe we can add a footnote there that says:

Refer to section 1.6 NAMESPACE.  You can export only a subset of all R
objects to make them on user level. So that you don't need to write
Rd files for un-exported ones. 

Thanks!