[Rd] Documentation: add a bit note (PR#9066)

[feimingchen at yahoo.com]

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!