chore: Add examples

Author: gadenbuie

R/btw_this.R

@@ -105,6 +105,9 @@ as_btw_capture <- function(x) {
 #'   Includes the `.Last.value`, i.e. the result of the last expression
 #'   evaluated in your R console.
 #'
+#' @examples
+#' btw_this("?btw::btw_this")
+#'
 #' @param x A character string
 #' @param ... Ignored.
 #' @param caller_env The caller environment.

R/tool-environment.R

@@ -24,6 +24,10 @@ btw_this.environment <- function(x, ..., items = NULL) {
 
 #' Tool: Describe an environment
 #'
+#' @examples
+#' my_cars <- mtcars[mtcars$mpg > 25, ]
+#'  btw_tool_env_describe_environment("my_cars")
+#'
 #' @param environment An environment to describe.
 #' @param ... Ignored.
 #' @inheritParams btw_this.environment

R/tool-files.R

@@ -3,6 +3,13 @@ NULL
 
 #' Tool: List files
 #'
+#' @examples
+#' withr::with_tempdir({
+#'   write.csv(mtcars, "mtcars.csv")
+#'
+#'   btw_tool_files_list_files(type = "file")
+#' })
+#'
 #' @param path Path to a directory or file for which to get information. The
 #'   `path` must be in the current working directory. If `path` is a directory,
 #'   we use [fs::dir_info()] to list information about files and directories in
@@ -104,6 +111,13 @@ btw_tool_files_list_files <- function(
 
 #' Tool: Read a file
 #'
+#' @examples
+#' withr::with_tempdir({
+#'   write.csv(mtcars, "mtcars.csv")
+#'
+#'   btw_tool_files_read_text_file("mtcars.csv", max_lines = 5)
+#' })
+#'
 #' @param path Path to a file for which to get information. The `path` must be
 #'   in the current working directory.
 #' @param max_lines Number of lines to include. Defaults to 1,000 lines.

R/tool-rstudioapi.R

@@ -7,6 +7,9 @@ NULL
 #' Reads the current file using the \pkg{rstudioapi}, which works in RStudio,
 #' Positron and VS Code (with the vscode-r extension).
 #'
+#' @examplesIf rstudioapi::hasFun("getSourceEditorContext")
+#' btw_tool_ide_read_current_editor(consent = TRUE)
+#'
 #' @param selection Should only the selected text be included? If no text is
 #'   selected, the full file contents are returned.
 #' @param consent Boolean indicating whether the user has consented to reading