<p><div><div><div><div data-show-faces="false" data-height="21" data-width="100" data-layout="button_count" data-send="true" data-href="https://www.r-bloggers.com/r-deprecate-functions-with-roxygen2-2/"></div></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="http://mirai-solutions.ch/news/2017/12/05/roxygen2-deprecate/"> R-feed</a></strong>, and kindly contributed to <a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers)</a> </div>
<p>We show how to use <strong>roxygen2</strong> tags and templates for deprecating existing documented functions.</p>
<p><span></span></p>
<h4>Introduction</h4>
<p>Package <strong>roxygen2</strong> provides a powerful way of documenting packages and objects inside them. In particular, great flexibility is available for organizing the documentation content in source files and templates, and render it as desired in the corresponding help pages.</p>
<p>We can leverage on this flexibility to adapt an existing package documentation upon making a function <em>deprecated</em> (and similarly <em>defunct</em>). As stated in the base-<strong>R</strong> ‘Marking Objects as Deprecated’ documentation (<code>help(Deprecated)</code>):</p>
<blockquote>
<p>The original help page for these functions is often available at help(“oldName-deprecated”) (note the quotes). Functions should be listed in help(“pkg-deprecated”) for an appropriate pkg, including base.</p>
</blockquote>
<h4>Deprecate existing functions</h4>
<p>We show how an existing and documented function <code>myFun</code> in package <strong>ourPkg</strong> can be deprecated, and the documentation adjusted accordingly by re-arranging the <strong>roxygen2</strong> documentation content.</p>
<div>
<div>
<pre><code><span>## myFun.r</span><span>
</span><span>#' @title My function.</span><span>
</span><span>#' @description My function.</span><span>
</span><span>#' @param arg1 My first argument.</span><span>
</span><span>#' @param arg2 My second argument.</span><span>
</span><span>#' @return My return value.</span><span>
</span><span>#' @export</span><span>
</span><span>myFun</span><span> </span><span>&lt;-</span><span> </span><span>function</span><span>(</span><span>arg1</span><span>,</span><span> </span><span>arg2</span><span>)</span><span> </span><span>{</span><span>
</span><span>&quot;My return value&quot;</span><span>
</span><span>}</span><span>
</span></code></pre>
</div>
</div>
<p>Let us assume a new function <code>myNewFunction</code> exists as a replacement for the old <code>myFun</code>, which becomes deprecated. We want to achieve the following</p>
<ul>
<li>list <code>myFun</code> in <code>help(&quot;ourPkg-deprecated&quot;&quot;)</code>, along with its replacement;</li>
<li>make its original documentation available via <code>help(&quot;myFun-deprecated&quot;)</code>.</li>
</ul>
<p>This can be obtained by</p>
<ul>
<li>creating generic content for <code>help(&quot;ourPkg-deprecated&quot;&quot;)</code>;</li>
<li>adjusting the existing <code>myFun</code> documentation content.</li>
</ul>
<h5>Package-level documentation</h5>
<p>Generic content for <code>help(&quot;ourPkg-deprecated&quot;)</code> is defined in its own source file:</p>
<div>
<div>
<pre><code><span>## ourPkg-deprecated.r</span><span>
</span><span>#' @title Deprecated functions in package \pkg{ourPkg}.</span><span>
</span><span>#' @description The functions listed below are deprecated and will be defunct in</span><span>
</span><span>#' the near future. When possible, alternative functions with similar</span><span>
</span><span>#' functionality are also mentioned. Help pages for deprecated functions are</span><span>
</span><span>#' available at \code{help(&quot;</span></code></pre></div></div>