Roll dockerignore documentation

Author: coatless

R/dockerignore-core.R

@@ -1,6 +1,24 @@
-#' Create a new dockerignore object
+#' Create a new `dockerignore` object
 #'
-#' @return A new, empty dockerignore object
+#' Creates an empty `dockerignore`` object that can be populated with patterns
+#' to ignore during Docker builds.
+#'
+#' @return
+#' A `dockerignore` object with a `patterns` character vector
+#'
+#' @examples
+#' # Create a new dockerignore object
+#' di <- dockerignore()
+#' 
+#' # Add patterns
+#' di <- di_add(di, c(".git/", "*.log"))
+#'
+#' @seealso
+#' [di_add()] for adding patterns,
+#' [write_dockerignore()] for writing to a .dockerignore file, &
+#' [dk_template_ignore_common()] for adding common patterns
+#'
+#' @family dockerignore core functions
 #' @export
 dockerignore <- function() {
   structure(
@@ -11,10 +29,29 @@ dockerignore <- function() {
   )
 }
 
-#' Combine multiple dockerignore objects
+#' Combine multiple `dockerignore` objects
+#'
+#' Merges patterns from multiple `dockerignore` objects into a single one.
+#' This is useful for combining different template patterns.
+#'
+#' @param ... `dockerignore` objects to combine
 #'
-#' @param ... Dockerignore objects to combine
-#' @return A new dockerignore object with combined patterns
+#' @return
+#' A new `dockerignore` object with combined patterns from all inputs
+#'
+#' @examples
+#' # Create dockerignore objects with different patterns
+#' di_git <- dk_template_ignore_git()
+#' di_r <- dk_template_ignore_r()
+#' 
+#' # Combine them
+#' di_combined <- c(di_git, di_r)
+#'
+#' @seealso
+#' [dockerignore()] for creating a new `dockerignore` object &
+#' [dk_template_ignore_common()] for adding common patterns
+#'
+#' @family dockerignore core functions
 #' @export
 c.dockerignore <- function(...) {
   args <- list(...)
@@ -39,17 +76,53 @@ c.dockerignore <- function(...) {
 
 #' Test if an object is a dockerignore
 #'
+#' Checks whether the provided object is a valid `dockerignore` class object.
+#'
 #' @param x Object to test
-#' @return TRUE if x is a dockerignore, FALSE otherwise
+#'
+#' @return
+#' `TRUE` if `x` is a dockerignore object, `FALSE` otherwise
+#'
+#' @examples
+#' di <- dockerignore()
+#' is_dockerignore(di)  # TRUE
+#' is_dockerignore(list())  # FALSE
+#'
+#' @seealso
+#' [dockerignore()] for creating a dockerignore object &
+#' [check_dockerignore()] for ensuring an object is a dockerignore (with error)
+#'
+#' @family dockerignore core functions
 #' @export
 is_dockerignore <- function(x) {
   inherits(x, "dockerignore")
 }
 
-#' Ensure an object is a dockerignore
+#' Ensure an object is a `dockerignore`
+#'
+#' Verifies that the provided object is a valid `dockerignore` class object,
+#' throwing an error if not. Useful for validation inside functions that
+#' expect `dockerignore` objects.
 #'
 #' @param dockerignore Object to check
-#' @return Invisible TRUE if valid, error otherwise
+#'
+#' @return
+#' Invisibly returns `TRUE` if valid, otherwise throws an error
+#'
+#' @examples
+#' di <- dockerignore()
+#' check_dockerignore(di)  # Valid, returns TRUE invisibly
+#' 
+#' \dontrun{
+#' # This would throw an error
+#' check_dockerignore(list())
+#' }
+#'
+#' @seealso
+#' [is_dockerignore()] for checking if an object is a dockerignore &
+#' [dockerignore()] for creating a dockerignore object
+#'
+#' @family dockerignore core functions
 #' @export
 check_dockerignore <- function(dockerignore) {
   if (!is_dockerignore(dockerignore)) {
@@ -60,8 +133,26 @@ check_dockerignore <- function(dockerignore) {
 
 #' Print method for dockerignore objects
 #'
-#' @param x A dockerignore object
+#' Displays the contents of a dockerignore object in a readable format,
+#' showing each pattern on a new line as it would appear in an
+#' actual .dockerignore file.
+#'
+#' @param x A `dockerignore` object
 #' @param ... Additional arguments (not used)
+#'
+#' @return
+#' Invisibly returns the dockerignore object
+#'
+#' @examples
+#' di <- dockerignore() |>
+#'   di_add(c(".git/", "*.log", "node_modules/"))
+#' print(di)
+#'
+#' @seealso
+#' [dockerignore()] for creating a dockerignore object &
+#' [write_dockerignore()] for writing to a .dockerignore file
+#'
+#' @family dockerignore core functions
 #' @export
 print.dockerignore <- function(x, ...) {
   check_dockerignore(x)

R/dockerignore-io.R

@@ -1,7 +1,30 @@
-#' Read a .dockerignore file
+#' Read a **.dockerignore** file
 #'
-#' @param file Path to .dockerignore file
-#' @return A dockerignore object
+#' Reads a **.dockerignore** file from disk into a `dockerignore` object that
+#' can be manipulated programmatically.
+#'
+#' @param file Path to **.dockerignore** file (default: `".dockerignore"`)
+#'
+#' @return
+#' A `dockerignore` object containing the parsed patterns
+#'
+#' @examples
+#' \dontrun{
+#' # Read an existing .dockerignore file
+#' di <- read_dockerignore()
+#' 
+#' # Add more patterns
+#' di <- di_add(di, "*.tmp")
+#' }
+#'
+#' @details
+#' Empty lines and comments (lines starting with `#`) are filtered out.
+#'
+#' @seealso
+#' [dockerignore()] for creating a new dockerignore object &
+#' [write_dockerignore()] for writing a dockerignore to disk
+#'
+#' @family dockerignore I/O functions
 #' @export
 read_dockerignore <- function(file = ".dockerignore") {
   if (!file.exists(file)) {
@@ -21,11 +44,29 @@ read_dockerignore <- function(file = ".dockerignore") {
   di
 }
 
-#' Write a dockerignore object to a file
+#' Write a `dockerignore` object to a file
+#'
+#' Writes a `dockerignore` object to disk as a formatted **.dockerignore** file.
+#'
+#' @param dockerignore A `dockerignore` object
+#' @param file Output file path (default: `".dockerignore"`)
+#'
+#' @return
+#' Invisibly returns the `dockerignore` object
+#'
+#' @examples
+#' \dontrun{
+#' # Create and write a .dockerignore file
+#' dockerignore() |>
+#'   di_add(c(".git/", "*.log")) |>
+#'   write_dockerignore()
+#' }
+#'
+#' @seealso
+#' [read_dockerignore()] for reading a .dockerignore file from disk &
+#' [dockerignore()] for creating a new dockerignore object
 #'
-#' @param dockerignore A dockerignore object
-#' @param file Output file path (default: ".dockerignore")
-#' @return Invisible dockerignore object
+#' @family dockerignore I/O functions
 #' @export
 write_dockerignore <- function(dockerignore, file = ".dockerignore") {
   check_dockerignore(dockerignore)