document: Document (Chunks of) an R Code File

In document: Run 'roxygen2' on (Chunks of) Single Code Files

Document (Chunks of) an R Code File

Description

Document (Chunks of) an R Code File

Usage

document(
  file_name,
  working_directory = NULL,
  output_directory = tempdir(),
  dependencies = NULL,
  sanitize_Rd = TRUE,
  runit = FALSE,
  check_package = TRUE,
  check_as_cran = check_package,
  stop_on_check_not_passing = check_package,
  clean = FALSE,
  debug = TRUE,
  ...
)

Arguments

file_name	The name of the R code file to be documented.
working_directory	A working directory. Keep the default.
output_directory	The directory to put the documentation into. You might want to use dirname(file_name).
dependencies	A character vector of package names the functions depend on.
sanitize_Rd	Remove strange characters from Rdconv?
runit	Convert the text received from the help files if running RUnit? Do not bother, this is for Unit testing only.
check_package	Run R CMD check the sources? See Note below.
check_as_cran	Use the --as-cran flag with R CMD check?
stop_on_check_not_passing	Stop if R CMD check does not pass?
clean	Delete the working directory?
debug	For internal use only: Summarize errors for travis?
...	Arguments passed to get_lines_between_tags.

Value

A list containing

pdf_path

The path to the pdf file produced,

txt_path

The path to the text file produced,

html_path

The path to the html file produced,

check_result

The return value of rcmdcheck::rcmdcheck()

Note

One of the main features of R CMD check is checking for code/documentation mismatches (it behaves pretty much like doxygen). No build system can check whether your documentation is useful, but R CMD check checks if it is formally matching your code. This check is the basic idea behind document. The possibility to disable the R CMD check is there to disable CPU consuming checks while testing the package. Stick with the default! And do not forget to export your functions using the line
#' @export
should you provide examples.

Examples

res <- document(file_name = system.file("files", "minimal.R",
                                        package = "document"),
                check_package = FALSE) # this is for the sake of CRAN cpu
                # time only. _Always_ stick with the default!

# View R CMD check results. If we had set check_package to TRUE in the above
# example, we now could retrieve the check results via:
cat(res[["check_result"]][["output"]][["stdout"]], sep = "\n")
cat(res[["check_result"]][["output"]][["stderr"]], sep = "\n")

# Copy docmentation to current working directory.
# This writes to your disk, so it's disabled.
# Remove or comment out the next line to enable.
if (FALSE)
    file.copy(res[["pdf_path"]], getwd())

document documentation built on July 9, 2023, 5:22 p.m.