---
title: Rd2roxygen
subtitle: Convert Rd to roxygen documentation
author: "Yihui Xie"
slug: rd2roxygen
githubEditURL: https://github.com/yihui/Rd2roxygen/edit/master/vignettes/Rd2roxygen.Rmd
output:
  html:
    meta:
      css: ["@default"]
vignette: >
  %\VignetteEngine{litedown::vignette}
  %\VignetteIndexEntry{Rd2roxygen: Convert Rd to roxygen documentation and utilities to enhance R documentation}
---

```{r, setup, include=FALSE}
litedown::reactor(attr.source = 'r')
```

The package [**Rd2roxygen**](https://github.com/yihui/Rd2roxygen) helps R
package developers who used to write R documentation in the raw LaTeX-like
commands but now want to switch their documentation to
[**roxygen2**](https://cran.r-project.org/package=roxygen2), which is a
convenient tool for developers, since we can write documentation as inline
comments, e.g.

```{r roxygen-ex, attr.output='r'}
## the source code of the function `parse_and_save`
ex.file = system.file('examples', 'parse_and_save.R', package = 'Rd2roxygen')
xfun::file_string(ex.file)
```

With **roxygen2** (typically using `roxygenize()`), we can create the real Rd
file from the above source code like this:

```{r rd-ex, attr.output='tex'}
rd.file = system.file('examples', 'parse_and_save.Rd', package = 'Rd2roxygen')
xfun::file_string(rd.file)
```

The **Rd2roxygen** package goes exactly in the *opposite* way -- it parses the
Rd files and turns them back to roxygen comments. We can either do this job on
single Rd files, or just convert the whole package. The latter might be more
useful for developers who are considering the transition from Rd to roxygen.

## Convert a whole package

The function `Rd2roxygen::Rd2roxygen()` can take a path of a source package,
parse all the Rd files under the `man` directory, and write the roxygen comments
right above the source code of the functions under the `R` directory. See
`?Rd2roxygen` for an example.

``` r
Rd2roxygen::Rd2roxygen('path/to/source/pkg')
## there must be 'man' and 'R' directories under this path
```

Note the path to the package should not be `.`. You are recommended to call this
function in the directory that contains the source package.

## Parse a single Rd file

We can parse a single Rd file and create the roxygen comments as well with
`parse_file()` and `create_roxygen()`, e.g.

```{r parse-file}
library(Rd2roxygen)
## we can specify the roxygen comments prefix (#' by default)
options(roxygen.comment = "##' ")
str(info <- parse_file(rd.file))
# parse_and_save() combines these two steps
xfun::raw_string(create_roxygen(info))
```

## Roxygenize and build a package

This package also provides a tool `roxygen_and_build()` (or in short `rab()`) to
help us build the package.

The main feature of `rab()` is the option to "reformat" the code in the usage
and example sections. If we specify `reformat = TRUE` in `rab()`, the code will
be reformated like this:

``` r
## original code
rab=function(pkg,build=TRUE,install=FALSE,
check=FALSE,check.opts='',remove.check=TRUE,reformat=TRUE,...){}
```

``` r
## the reformatted code; note the spaces and indent
rab = function(pkg, build = TRUE, install = FALSE, check = FALSE,
    check.opts = "", remove.check = TRUE, reformat = TRUE, ...) {
}
```

Note this functionality depends on the package
[**formatR**](https://yihui.org/formatr/), and sometimes it might not be
possible to reformat the code, e.g. the `\dontrun{}` command in Rd can contain
arbitrary texts, which means there could be illegal R expressions and
**formatR** will be unable to format the code. In this case, the original code
will not be reformatted and a message will be printed on screen.