document: Document (Chunks of) an R Code File

View source: R/document.R

documentR Documentation

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 Aug. 19, 2022, 5:23 p.m.