Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/r-lib/roxygen2
Generate R package documentation from inline R comments
https://github.com/r-lib/roxygen2
devtools documentation r
Last synced: 3 months ago
JSON representation
Generate R package documentation from inline R comments
- Host: GitHub
- URL: https://github.com/r-lib/roxygen2
- Owner: r-lib
- License: other
- Created: 2011-05-18T08:23:27.000Z (over 13 years ago)
- Default Branch: main
- Last Pushed: 2024-06-07T02:28:43.000Z (5 months ago)
- Last Synced: 2024-06-11T17:10:10.148Z (5 months ago)
- Topics: devtools, documentation, r
- Language: R
- Homepage: https://roxygen2.r-lib.org
- Size: 15.9 MB
- Stars: 579
- Watchers: 19
- Forks: 230
- Open Issues: 115
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Support: .github/SUPPORT.md
Awesome Lists containing this project
- jimsghstars - r-lib/roxygen2 - Generate R package documentation from inline R comments (R)
README
# roxygen2 
[](https://CRAN.R-project.org/package=roxygen2)
[](https://github.com/r-lib/roxygen2/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/r-lib/roxygen2?branch=main)
The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to automatically generate `.Rd` files in `man/`, `NAMESPACE`, and, if needed, the `Collate` field in `DESCRIPTION`.
## Installation
```R
# Install roxygen2 from CRAN
install.packages("roxygen2")
# Or the development version from GitHub:
# install.packages("pak")
pak::pak("r-lib/roxygen2")
```
## Usage
The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to produce Rd files in the `man/` directory. Here's a [simple example](https://stringr.tidyverse.org/reference/str_length.html) from the stringr package:
```R
#' The length of a string
#'
#' Technically this returns the number of "code points", in a string. One
#' code point usually corresponds to one character, but not always. For example,
#' an u with a umlaut might be represented as a single character or as the
#' combination a u and an umlaut.
#'
#' @inheritParams str_detect
#' @return A numeric vector giving number of characters (code points) in each
#' element of the character vector. Missing string have missing length.
#' @seealso [stringi::stri_length()] which this function wraps.
#' @export
#' @examples
#' str_length(letters)
#' str_length(NA)
#' str_length(factor("abc"))
#' str_length(c("i", "like", "programming", NA))
str_length <- function(string) {
}
```
When you `roxygenise()` (or `devtools::document()`) your package these comments will be automatically transformed to the `.Rd` that R uses to generate the documentation you see when you type `?str_length`.
## Learn more
To get started, first read `vignette("roxygen2")`. Then read more about the specific package component that you want to generate:
* Start with `vignette("rd")` to learn how document your functions with roxygen2.
* `vignette("rd-other")` discusses how to document other things like datasets, the package itself, and the various pieces used by R's OOP systems.
* `vignette("rd-formatting")` gives the details of roxygen2's rmarkdown support.
* `vignette("reuse")` demonstrates the tools available to reuse documentation in multiple places.
* `vignette("namespace")` describes how to generate a `NAMESPACE` file, how namespacing works in R, and how you can use roxygen2 to be specific about what your package needs and supplies.
* For the `Collate` field in the `DESCRIPTION`, see `?update_collate()`.