File: roxygen2.html

package info (click to toggle)
r-cran-roxygen2 7.3.3-1
links: PTS, VCS
area: main
in suites: sid
size: 1,940 kB
sloc: cpp: 351; sh: 14; makefile: 2
file content (483 lines) | stat: -rw-r--r-- 14,584 bytes
<!DOCTYPE html>

<html>

<head>

<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />

<meta name="viewport" content="width=device-width, initial-scale=1" />



<title>Get started with roxygen2</title>

<script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
// be compatible with the behavior of Pandoc < 2.8).
document.addEventListener('DOMContentLoaded', function(e) {
  var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
  var i, h, a;
  for (i = 0; i < hs.length; i++) {
    h = hs[i];
    if (!/^h[1-6]$/i.test(h.tagName)) continue;  // it should be a header h1-h6
    a = h.attributes;
    while (a.length > 0) h.removeAttribute(a[0].name);
  }
});
</script>

<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>



<style type="text/css">
code {
white-space: pre;
}
.sourceCode {
overflow: visible;
}
</style>
<style type="text/css" data-origin="pandoc">
html { -webkit-text-size-adjust: 100%; }
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } 
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.at { color: #7d9029; } 
code span.bn { color: #40a070; } 
code span.bu { color: #008000; } 
code span.cf { color: #007020; font-weight: bold; } 
code span.ch { color: #4070a0; } 
code span.cn { color: #880000; } 
code span.co { color: #60a0b0; font-style: italic; } 
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.do { color: #ba2121; font-style: italic; } 
code span.dt { color: #902000; } 
code span.dv { color: #40a070; } 
code span.er { color: #ff0000; font-weight: bold; } 
code span.ex { } 
code span.fl { color: #40a070; } 
code span.fu { color: #06287e; } 
code span.im { color: #008000; font-weight: bold; } 
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.kw { color: #007020; font-weight: bold; } 
code span.op { color: #666666; } 
code span.ot { color: #007020; } 
code span.pp { color: #bc7a00; } 
code span.sc { color: #4070a0; } 
code span.ss { color: #bb6688; } 
code span.st { color: #4070a0; } 
code span.va { color: #19177c; } 
code span.vs { color: #4070a0; } 
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } 
</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try { var rules = sheets[i].cssRules; } catch (e) { continue; }
    var j = 0;
    while (j < rules.length) {
      var rule = rules[j];
      // check if there is a div.sourceCode rule
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") {
        j++;
        continue;
      }
      var style = rule.style.cssText;
      // check if color or background-color is set
      if (rule.style.color === '' && rule.style.backgroundColor === '') {
        j++;
        continue;
      }
      // replace div.sourceCode by a pre.sourceCode rule
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
</script>




<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap; 
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }

code > span.kw { color: #555; font-weight: bold; } 
code > span.dt { color: #902000; } 
code > span.dv { color: #40a070; } 
code > span.bn { color: #d14; } 
code > span.fl { color: #d14; } 
code > span.ch { color: #d14; } 
code > span.st { color: #d14; } 
code > span.co { color: #888888; font-style: italic; } 
code > span.ot { color: #007020; } 
code > span.al { color: #ff0000; font-weight: bold; } 
code > span.fu { color: #900; font-weight: bold; } 
code > span.er { color: #a61717; background-color: #e3d2d2; } 
</style>




</head>

<body>




<h1 class="title toc-ignore">Get started with roxygen2</h1>



<p>Documentation is one of the most important aspects of good code.
Without it, users won’t know how to use your package, and are unlikely
to do so. Documentation is also useful for you in the future (so you
remember what the heck you were thinking!), and for other developers
working on your package. The goal of roxygen2 is to make documenting
your code as easy as possible.</p>
<p>R provides a standard way of documenting packages: you write
<code>.Rd</code> files in the <code>man/</code> directory. These files
use a custom syntax, loosely based on LaTeX. roxygen2 provides a number
of advantages over writing <code>.Rd</code> files by hand:</p>
<ul>
<li><p>Code and documentation are adjacent so when you modify your code,
it’s easy to remember that you need to update the
documentation.</p></li>
<li><p>roxygen2 dynamically inspects the objects that it’s documenting,
so it can automatically add data that you’d otherwise have to write by
hand.</p></li>
<li><p>It abstracts over the differences in documenting S3 and S4
methods, generics and classes, so you need to learn fewer
details.</p></li>
</ul>
<p>As well as generating <code>.Rd</code> files, roxygen will also
create a <code>NAMESPACE</code> for you, and will manage the
<code>Collate</code> field in <code>DESCRIPTION</code>.</p>
<div id="learn-more" class="section level2">
<h2>Learn more</h2>
<p>This vignette provides a high-level description of roxygen2 and the
overall workflow you’ll use with it. The other vignettes provide more
detail on the most important individual components:</p>
<ul>
<li><p>Start with <code>vignette(&quot;rd&quot;)</code> to learn how document your
functions with roxygen2.</p></li>
<li><p><code>vignette(&quot;rd-other&quot;)</code> discusses how to document other
things like datasets, the package itself, and the various pieces used by
R’s OOP systems.</p></li>
<li><p><code>vignette(&quot;rd-formatting&quot;)</code> gives the details of
roxygen2’s rmarkdown support.</p></li>
<li><p><code>vignette(&quot;reuse&quot;)</code> demonstrates the tools available
to reuse documentation in multiple places.</p></li>
<li><p><code>vignette(&quot;namespace&quot;)</code> describes how to generate a
<code>NAMESPACE</code> file, how namespacing works in R, and how you can
use roxygen2 to be specific about what your package needs and
supplies.</p></li>
</ul>
</div>
<div id="running-roxygen" class="section level2">
<h2>Running roxygen</h2>
<p>There are three main ways to run roxygen:</p>
<ul>
<li><p><code>roxygen2::roxygenise()</code>.</p></li>
<li><p><code>devtools::document()</code>.</p></li>
<li><p><code>Ctrl + Shift + D</code>, if you’re using RStudio.</p></li>
</ul>
<p>You can mix handwritten Rd and roxygen2; roxygen2 will never
overwrite a file it didn’t create.</p>
</div>
<div id="basic-process" class="section level2">
<h2>Basic process</h2>
<p>There are three steps in the transformation from roxygen comments in
your source file to human readable documentation:</p>
<ol style="list-style-type: decimal">
<li>You add roxygen comments to your source file.</li>
<li><code>roxygen2::roxygenise()</code> converts roxygen comments to
<code>.Rd</code> files.</li>
<li>R converts <code>.Rd</code> files to human readable
documentation.</li>
</ol>
<p>The process starts when you add specially formatted roxygen comments
to your source file. Roxygen comments start with <code>#&#39;</code> so you
can continue to use regular comments for other purposes.</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a><span class="co">#&#39; Add together two numbers</span></span>
<span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a><span class="co">#&#39;</span></span>
<span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a><span class="co">#&#39; @param x A number.</span></span>
<span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a><span class="co">#&#39; @param y A number.</span></span>
<span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a><span class="co">#&#39; @return A number.</span></span>
<span id="cb1-6"><a href="#cb1-6" tabindex="-1"></a><span class="co">#&#39; @examples</span></span>
<span id="cb1-7"><a href="#cb1-7" tabindex="-1"></a><span class="co">#&#39; add(1, 1)</span></span>
<span id="cb1-8"><a href="#cb1-8" tabindex="-1"></a><span class="co">#&#39; add(10, 1)</span></span>
<span id="cb1-9"><a href="#cb1-9" tabindex="-1"></a>add <span class="ot">&lt;-</span> <span class="cf">function</span>(x, y) {</span>
<span id="cb1-10"><a href="#cb1-10" tabindex="-1"></a>  x <span class="sc">+</span> y</span>
<span id="cb1-11"><a href="#cb1-11" tabindex="-1"></a>}</span></code></pre></div>
<p>For the example above, this will generate <code>man/add.Rd</code>
that looks like:</p>
<pre class="rd"><code>% Generated by roxygen2: do not edit by hand
% Please edit documentation in ./&lt;text&gt;
\name{add}
\alias{add}
\title{Add together two numbers}
\usage{
add(x, y)
}
\arguments{
\item{x}{A number.}

\item{y}{A number.}
}
\value{
A number.
}
\description{
Add together two numbers
}
\examples{
add(1, 1)
add(10, 1)
}</code></pre>
<p>Rd files are a special file format loosely based on LaTeX. You can
read more about the Rd format in the <a href="https://cran.r-project.org/doc/manuals/R-exts.html#Rd-format">R
extensions</a> manual. With roxygen2, there are few reasons to know
about Rd files, so here I’ll avoid discussing them as much as possible,
focusing instead on what you need to know about roxygen2.</p>
<p>When you use <code>?x</code>, <code>help(&quot;x&quot;)</code> or
<code>example(&quot;x&quot;)</code> R looks for an Rd file containing
<code>\alias{x}</code>. It then parses the file, converts it into HTML
and displays it. These functions look for an Rd file in
<em>installed</em> packages. This isn’t very useful for package
development, because you want to use the <code>.Rd</code> files in the
<em>source</em> package. For this reason, we recommend that you use
roxygen2 in conjunction with devtools: <code>devtools::load_all()</code>
automatically adds shims so that <code>?</code> and friends will look in
the development package.</p>
</div>



<!-- code folding -->


<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

</body>
</html>