deprecating loadRcppModules

- adding .Deprecate() call to function
- renaming manual page
- listing in new per-package Rcpp-deprecated page
- updating vignette
- added NEWS entry

Author: eddelbuettel

ChangeLog

@@ -1,10 +1,22 @@
-2013-05-15  Kevin Ushey <[email protected]>
+2016-05-06  Dirk Eddelbuettel  <[email protected]>
+
+        * R/loadRcppModules.R (loadRcppModules): Add call to .Deprecated
+        pointing out that loadModule is preferred
+        * man/Rcpp-deprecated.Rd: Added to list deprecated functions
+        * man/loadRcppModules-deprecated.Rd: Renamed to -deprecated, added link
+        to loadModule which is the preferred method
+
+        * vignettes/Rcpp-modules.Rnw: Updated with respect to loadRcppModules
+        deprecation and loadModule being preferred
+
+2016-04-15  Kevin Ushey <[email protected]>
 
         * src/attributes.cpp: Add a missing 'winslash = "/"'
 
-2013-05-14  J.J. Allaire <[email protected]>
+2016-04-14  J.J. Allaire <[email protected]>
 
-        * src/attributes.cpp: Correct handling of dependent file paths on Windows (use winslash = "/")
+        * src/attributes.cpp: Correct handling of dependent file paths on
+        Windows (use winslash = "/") 
 
 2016-04-13  Dirk Eddelbuettel  <[email protected]>
 

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: Rcpp
 Title: Seamless R and C++ Integration
-Version: 0.12.4.5
-Date: 2016-04-15
+Version: 0.12.4.6
+Date: 2016-05-06
 Author: Dirk Eddelbuettel, Romain Francois, JJ Allaire, Kevin Ushey,
  Qiang Kou, Douglas Bates and John Chambers
 Maintainer: Dirk Eddelbuettel <[email protected]>

NAMESPACE

@@ -15,7 +15,7 @@ exportMethods(prompt, show, .DollarNames, initialize, "formals<-")
 export(Module,
        Rcpp.package.skeleton,
        populate,
-       loadRcppModules,
+       loadRcppModules,  # deprecated since Rcpp 0.12.5
        setRcppClass,
        loadRcppClass,
        loadModule,

R/loadRcppModules.R

@@ -15,7 +15,10 @@
 # You should have received a copy of the GNU General Public License
 # along with Rcpp.  If not, see <http://www.gnu.org/licenses/>.
 
-loadRcppModules <- function(direct=TRUE){
+loadRcppModules <- function(direct=TRUE) {
+    # deprecation added May 2016, 'loadModule' has been prefered for years
+    .Deprecated("loadModule")
+    
     ## hunt for the namespace of the package that calls this
     calls <- sys.calls()
     w <- which( sapply( calls, function(call){

inst/NEWS.Rd

@@ -20,6 +20,8 @@
     \itemize{
       \item An apparent race condition in Module loading seen with R 3.3.0 was
       fixed (Ben Goodrich in \ghpr{461} fixing \ghit{458}).
+      \item The (older) \code{loadRcppModules()} is now deprecated in favour of
+      \code{loadModule()} introduced around R 2.15.1 and Rcpp 0.9.11.
     }
   }
 }

man/Rcpp-deprecated.Rd

@@ -0,0 +1,11 @@
+\name{Rcpp-deprecated}
+\alias{Rcpp-deprecated}
+\title{Deprecated Functions in the Rcpp Package}
+\description{
+  These functions are provided for compatibility with older versions of the
+  \pkg{Rcpp} package only, and may be removed in future versions.
+}
+\details{
+  \code{loadRcppModules} calls should now be replaced by
+  \code{\link{loadModule}} calls, one per Module.
+}

man/loadModule.Rd

@@ -81,7 +81,7 @@ John Chambers
 \seealso{
 \code{\link{setRcppClass}()} to avoid the explicit call.
 
-\code{\link{loadRcppModules}()} for a shotgun procedure to load all
+\code{\link{loadRcppModules}()} for a (deprecated) shotgun procedure to load all
 modules.
 }
 \examples{

man/loadRcppModules.Rd renamed to man/loadRcppModules-deprecated.Rd

@@ -1,9 +1,12 @@
-\name{loadRcppModules}
+\name{loadRcppModules-deprecated}
 \alias{loadRcppModules}
 \title{
 Loads Rcpp modules on package startup
 }
 \description{
+  \emph{Note:} As of release 0.16.5, this function is deprecated;
+  \code{\link{loadModule}} should be used instead.
+  
 Function to simplify loading Rcpp modules contained in a package. 
 This function must be called from the \code{.onLoad} function of a package. 
 It uses the \code{RcppModules} field of the package \code{DESCRIPTION} file
@@ -18,7 +21,7 @@ loadRcppModules(direct=TRUE)
     namespace. Otherwise, the module is exposed. }
 }
 \seealso{
-    \code{\link{populate}}
+    \code{\link{populate}}, \code{\link{loadModule}}
 }
 \keyword{interface}
 

vignettes/Rcpp-modules.Rnw

@@ -908,11 +908,24 @@ options( prompt = " ", continue = " " )
 @
 
 <<eval=FALSE>>=
-import( Rcpp )
+import(Rcpp)
 @
 
+In some case we have found that explicitly naming a symbol can be preferable:
+
+<<eval=FALSE>>=
+import(Rcpp, evalCpp)
+@
+
+\subsubsection{Load the module}
+
+\paragraph{Deprecated older method using loadRcppModules} 
+
+Note: This approach is deprecated as of Rcpp 0.12.5, and now triggers a warning
+message.  Eventually this function will be withdrawn.
+
 The simplest way to load all functions and classes from a module directly
-into a package namespace is to use the \code{loadRcppModules} function
+into a package namespace used to be to use the \code{loadRcppModules} function
 within the \code{.onLoad} body.
 
 <<eval=FALSE>>=
@@ -937,6 +950,8 @@ with a default value of \texttt{TRUE}. With this default value, all content
 from the module is exposed directly in the package namespace. If set to
 \texttt{FALSE}, all content is exposed as components of the module.
 
+\paragraph{Preferred current method using loadModule}   
+
 Starting with release 0.9.11, an alternative is provided by the
 \code{loadModule()} function which takes the module name as an argument.
 It can be placed in any \code{.R} file in the package. This is useful as it allows to load