Suppose you have a script
system.file("files", "minimal.R", package = "document")
path <-cat(readLines(path), sep = "\n")
#' Nothing Good For
#'
#' Just prints "foo!".
#' @author Your Name <you@@somewhe.re>
#' @param x Not needed.
#' @return NULL
#' @export
#' @examples
#' foo(x = 2)
foo <- function(x) {
print("foo!")
return(invisible(NULL))
}
#' Uhh
#'
#' Just prints "bar!".
#' @author Your Name <you@@somewhe.re>
#' @return NULL
#' @export
#' @examples
#' bar()
bar <- function() {
print("bar!")
return(invisible(NULL))
}
Then
document::document(file_name = path, check_package = FALSE) d <-
## Warning: roxygen2 requires Encoding: "UTF-8"
## ℹ Current encoding is NA
creates a Portable Document Format (pdf) file, an Hypertext Markup Language (html) file and a plain text file. The plain text reads
cat(readLines(d[["txt_path"]]), sep = "\n")
Uhh
Description:
Just prints "bar!".
Usage:
bar()
Author(s):
Your Name <[email protected]>
Examples:
bar()
Nothing Good For
Description:
Just prints "foo!".
Usage:
foo(x)
Arguments:
x: Not needed.
Author(s):
Your Name <[email protected]>
Examples:
foo(x = 2)
You can view a copy of the html file here. The pdf file resembles a package’s documentation pdf file.
By default, document
checks the temporary package it creates from your code file using R CMD check. The corresponding call would be:
res <- document(file_name = system.file("files", "minimal.R",
package = "document"),
check_package = TRUE)
After that you could display the check results with:
cat(res[["check_result"]][["output"]][["stdout"]], sep = "\n")
cat(res[["check_result"]][["output"]][["stderr"]], sep = "\n")
Suppose you have a script
system.file("files", "simple.R", package = "document")
path <-cat(readLines(path), sep = "\n")
#!/usr/bin/Rscript --vanilla
#' \emph{File} simple.R
#'
#' Provide a simple example of a file using roxygen and standard R comments.
#'
#' @note This header will show up in the documentation, but it's got nothing to
#' do with the R statements below. Usually this is not intended.
#' @section Warning: DO NOT CHANGE THE FOLLWOWING THREE LINES.
#' @docType data
#' @name A Header for
NULL
# ROXYGEN_STOP
#% Front Matter
##% load packages
library("methods") # load an example package from the standard library
##% load local code
# This would usually be functions defined and stored away in files.
##% define local functions
# ROXYGEN_START
#' a first function example XXX
#'
#' This really is just an example, the function prints \code{utils::head()} and
#' \code{utils::str()} of the given \code{data.frame}.
#' @param df Name of a data.frame to ... do whatever needs to be done.
#' @return NULL. This is no good.
#' @export
#' @examples
#' data(iris, package = "datasets")
#' a_first_function(iris)
a_first_function <- function(df) {
message(paste("# Structure of", deparse(substitute(df)), ":"))
utils::str(df)
message(paste("# Head of", deparse(substitute(df)), ":"))
print(utils::head(df))
return(invisible(NULL))
}
# ROXYGEN_STOP
##% set "global" options
options(warn = 1)
#% Body Matter
##% Load data
data(iris, package = "datasets")
##% Analysize the data
a_first_function(iris)
#% Back Matter
Then you can write documentation using:
document::document(file_name = path, check_package = FALSE) d <-
## Warning: roxygen2 requires Encoding: "UTF-8"
## ℹ Current encoding is NA
cat(readLines(d[["txt_path"]]), sep = "\n")
_File_ simple.R
Description:
Provide a simple example of a file using roxygen and standard R
comments.
Warning:
DO NOT CHANGE THE FOLLWOWING THREE LINES.
Note:
This header will show up in the documentation, but it's got
nothing to do with the R statements below. Usually this is not
intended.
a first function example XXX
Description:
This really is just an example, the function prints
'utils::head()' and 'utils::str()' of the given 'data.frame'.
Usage:
a_first_function(df)
Arguments:
df: Name of a data.frame to ... do whatever needs to be done.
Value:
NULL. This is no good.
Examples:
data(iris, package = "datasets")
a_first_function(iris)
You can display the help page for one of the documented functions using
system.file("files", "minimal.R", package = "document")
path <-::man(x = path, topic = "foo") document
Nothing Good For
Description:
Just prints "foo!".
Usage:
foo(x)
Arguments:
x: Not needed.
Author(s):
Your Name <[email protected]>
Examples:
foo(x = 2)