Adds RCPP_EXPORT_AS, RCPP_EXPORT_WRAP, RCPP_EXPORT_CLASS paragraphs by MathurinD (closes #416)

Author: coatless

ChangeLog

@@ -1,3 +1,7 @@
+2016-11-18  James J Balamuta  <balamut2@illinois.edu>
+        * vignettes/Rcpp-extending: Switched to attributes and
+          added external class pointer macro notes by MathurinD 
+
 2016-11-16  Dirk Eddelbuettel  <edd@debian.org>
 
         * DESCRIPTION: Release 0.12.8

inst/NEWS.Rd

@@ -3,6 +3,13 @@
 \newcommand{\ghpr}{\href{https://github.com/RcppCore/Rcpp/pull/#1}{##1}}
 \newcommand{\ghit}{\href{https://github.com/RcppCore/Rcpp/issues/#1}{##1}}
 
+\section{Changes in Rcpp version 0.12.8 (2017-01-xx)}{
+    \item Changes in Rcpp Documentation:
+    \itemize{
+      \item Exposed pointers macros were included in the Rcpp Extending vignette
+       (MathurinD; James Balamuta in \ghpr{592} addressing \ghit{418}).
+    }
+}
 \section{Changes in Rcpp version 0.12.8 (2016-11-16)}{
   \itemize{
     \item Changes in Rcpp API:

vignettes/Rcpp-extending.Rnw

@@ -187,6 +187,18 @@ It should be noted that only the declaration is required. The implementation
 can appear after the \texttt{Rcpp.h} file is included, and therefore take
 full advantage of the \pkg{Rcpp} type system.
 
+Another non-intrusive option is to expose an external pointer. The macro 
+\texttt{RCPP\_EXPORT\_WRAP} provides an easy way to expose a \proglang{C++} class 
+to \proglang{R} as an external pointer. It can be used instead of specializing
+\texttt{Rcpp::wrap}, and should not be used simultaneously. 
+
+<<lang=cpp>>=
+#include RcppCommon.h
+#include foobar.h
+
+RCPP_EXPORT_WRAP(Bar);
+@
+
 \subsection{Templates and partial specialization}
 
 It is perfectly valid to declare a partial specialization for the
@@ -263,6 +275,28 @@ namespace Rcpp {
 #include <Rcpp.h>
 @
 
+Furthermore, another non-intrusive option is to opt for sharing an R 
+external pointer. The macro \texttt{RCPP\_EXPORT\_AS} provides an easy way to
+extend \texttt{Rcpp::as} to expose \proglang{R} external pointers to 
+\proglang{C++}. It can be used instead of specializing \texttt{Rcpp::as}, and 
+should not be used simultaneously.
+
+<<lang=cpp>>=
+#include RcppCommon.h
+#include foobar.h
+
+RCPP_EXPORT_AS(Bar);
+@
+
+With this being said, there is one additional macro that can be used to 
+simultaneously define both \texttt{Rcpp::wrap} and \texttt{Rcpp::as}
+specialization for an external pointer. The macro \texttt{RCPP\_EXPOSED\_CLASS} 
+can be use to transparently exchange a class between \proglang{R} and 
+\proglang{C++} as an external pointer. Do not simultaneously use it alongside
+\texttt{RCPP\_EXPOSED\_AS}, \texttt{RCPP\_EXPOSED\_WRAP}, \texttt{Rcpp::wrap}, or
+\texttt{Rcpp::as}.
+
+
 \subsection{Templates and partial specialization}
 
 The signature of \texttt{Rcpp::as} does not allow partial specialization.