From maechler at stat.math.ethz.ch  Fri Dec 16 11:50:07 2011
From: maechler at stat.math.ethz.ch (Martin Maechler)
Date: Fri, 16 Dec 2011 11:50:07 +0100
Subject: [Rd] Undocumented functions
In-Reply-To: <4EEB148F.1090802@auckland.ac.nz>
References: <CAM8ViJPmS_zJzsT54ymj7OZOFUXAKwsCz=Qs9ckk2ESLrr-mrw@mail.gmail.com>
	<4EEB148F.1090802@auckland.ac.nz>
Message-ID: <20203.8799.852966.833885@stat.math.ethz.ch>

>>>>> David Scott <d.scott at auckland.ac.nz>
>>>>>     on Fri, 16 Dec 2011 22:51:11 +1300 writes:

    > One easy way is to list the undocumented files in
    > pkg-internal.Rd. From the Writing R Extensions manual:

    > Note that all user-level objects in a package should be
    > documented; if a package pkg contains user-level objects
    > which are for ?internal? use 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.

    > Probably a perverse use of this facility, but it works,
    > and will even allow the package to pass check.

    > David Scott

Excuse me David,
but I think the above actually is pre-R-2.14.x advice.

Now that every (installed) package has a NAMESPACE anyway,
package authors really should use a NAMESPACE themselves
(instead of the "auto-generated at installation-time" one)
and export the non-internal function

Martin


    > On 16/12/2011 1:01 a.m., Nicola Sturaro Sommacal wrote:
    >> Hi!
    >> 
    >> I am building a package. This package will not submitted
    >> to CRAN.
    >> 
    >> I write the help files for the most important functions
    >> of my package, I cannot write it for all functions. This
    >> may sounds strange, but so there!
    >> 
    >> I know that all user-level functions should be
    >> documented, so I have to move my undocumented functions
    >> to a non-user-level. It's right?
    >> 
    >> To move my functions to a non-user-level I can write them
    >> as hidden functions, with a dot before the names. This
    >> require a very long check of my code to change the call
    >> to the function preceding it by a dot. So, this is not a
    >> real choice.  There are other way to reach my purpose?
    >> 
    >> Thank you very much for help.
    >> 
    >> Sincerely, Nicola

    > -- 
    > _________________________________________________________________
    > David Scott Department of Statistics The University of
    > Auckland, PB 92019 Auckland 1142, NEW ZEALAND Phone: +64 9
    > 923 5055, or +64 9 373 7599 ext 85055 Email:
    > d.scott at auckland.ac.nz, Fax: +64 9 373 7018



[Rd] Undocumented functions
Martin Maechler