From 34c2d710e2a91c1d63eb0a2edadda0c4be3ccb00 Mon Sep 17 00:00:00 2001
From: njtierney <nicholas.tierney@gmail.com>
Date: Fri, 17 Jan 2025 16:40:49 +1100
Subject: [PATCH] reuse documentation - resolve #149

---
 R/tar-terra-rast.R    | 18 +++++++++++-------
 R/tar-terra-sprc.R    |  4 ++++
 R/tar-terra-vect.R    |  9 +--------
 man/tar_terra_rast.Rd | 18 +++++++++++-------
 man/tar_terra_sds.Rd  | 13 +++++++++++++
 man/tar_terra_sprc.Rd | 13 +++++++++++++
 man/tar_terra_vect.Rd | 18 +++++++++++-------
 7 files changed, 64 insertions(+), 29 deletions(-)

diff --git a/R/tar-terra-rast.R b/R/tar-terra-rast.R
index c3696ae..d14ccb9 100644
--- a/R/tar-terra-rast.R
+++ b/R/tar-terra-rast.R
@@ -3,13 +3,17 @@
 #' Provides a target format for [terra::SpatRaster-class] objects.
 #'
 #' @details
-#' [terra::SpatRaster-class] objects do not contain raster data directly—they
-#' contain a C++ pointer to memory where the data is stored.  As a result, these
-#' objects are not portable between R sessions without special handling, which
-#' causes problems when including them in `targets` pipelines with
-#' `tar_target()`. `tar_terra_rast()` handles this issue by writing and reading
-#' the target as a geospatial file (specified by `filetype`) rather than saving
-#' the `SpatRaster` object itself.
+#' The terra package uses objects like [terra::SpatRaster-class],
+#' [terra::SpatVector-class], and [terra::SpatRasterDataset] (SDS) objects -
+#' these do not contain the data directly—they contain a C++ pointer to memory
+#' where the data is stored.  As a result, these objects are not portable
+#' between R sessions without special handling, which causes problems when
+#' including them in `targets` pipelines with [targets::tar_target()].
+#' The functions, [tar_terra_rast()], [tar_terra_sds()],
+#' [tar_terra_sprc()], [tar_terra_tiles()], and [tar_terra_vect()] handle this
+#' issue by writing and reading the target as a geospatial file (specified by
+#' `filetype`) rather than saving the relevant object (e.g., `SpatRaster`,
+#' `SpatVector`, etc.), itself.
 #'
 #'
 #' @param name Symbol, name of the target. A target name must be a valid name
diff --git a/R/tar-terra-sprc.R b/R/tar-terra-sprc.R
index e1aa5b9..f1381fe 100644
--- a/R/tar-terra-sprc.R
+++ b/R/tar-terra-sprc.R
@@ -3,6 +3,8 @@
 #' Provides a target format for [terra::SpatRasterCollection] objects,
 #'   which have no restriction in the extent or other geometric parameters.
 #'
+#' @inherit tar_terra_rast details
+#'
 #' @param name Symbol, name of the target. A target name must be a valid name
 #'   for a symbol in R, and it must not start with a dot. See
 #'   [targets::tar_target()] for more information.
@@ -129,6 +131,8 @@ tar_terra_sprc <- function(
 #' Provides a target format for [terra::SpatRasterDataset] objects,
 #'   which hold sub-datasets, each a `SpatRaster` that can have multiple layers.
 #'
+#' @inherit tar_terra_rast details
+#'
 #' @param name Symbol, name of the target. A target name must be a valid name
 #'   for a symbol in R, and it must not start with a dot. See
 #'   [targets::tar_target()] for more information.
diff --git a/R/tar-terra-vect.R b/R/tar-terra-vect.R
index ee220ed..d6b7888 100644
--- a/R/tar-terra-vect.R
+++ b/R/tar-terra-vect.R
@@ -2,14 +2,7 @@
 #'
 #' Provides a target format for [terra::SpatVector-class] objects.
 #'
-#' @details
-#' [terra::SpatVector-class] objects do not contain vector data directly—they
-#' contain a C++ pointer to memory where the data is stored.  As a result, these
-#' objects are not portable between R sessions without special handling, which
-#' causes problems when including them in `targets` pipelines with
-#' `tar_target()`. `tar_terra_rast()` handles this issue by writing and reading
-#' the target as a geospatial file (specified by `filetype`) rather than saving
-#' the `SpatVector` object itself.
+#' @inherit tar_terra_rast details
 #'
 #' @param name Symbol, name of the target. A target name must be a valid name
 #'   for a symbol in R, and it must not start with a dot. See
diff --git a/man/tar_terra_rast.Rd b/man/tar_terra_rast.Rd
index 1a4242b..5af080d 100644
--- a/man/tar_terra_rast.Rd
+++ b/man/tar_terra_rast.Rd
@@ -226,13 +226,17 @@ target class "tar_stem" for use in a target pipeline
 Provides a target format for \link[terra:SpatRaster-class]{terra::SpatRaster} objects.
 }
 \details{
-\link[terra:SpatRaster-class]{terra::SpatRaster} objects do not contain raster data directly—they
-contain a C++ pointer to memory where the data is stored.  As a result, these
-objects are not portable between R sessions without special handling, which
-causes problems when including them in \code{targets} pipelines with
-\code{tar_target()}. \code{tar_terra_rast()} handles this issue by writing and reading
-the target as a geospatial file (specified by \code{filetype}) rather than saving
-the \code{SpatRaster} object itself.
+The terra package uses objects like \link[terra:SpatRaster-class]{terra::SpatRaster},
+\link[terra:SpatVector-class]{terra::SpatVector}, and \link[terra:SpatRaster-class]{terra::SpatRasterDataset} (SDS) objects -
+these do not contain the data directly—they contain a C++ pointer to memory
+where the data is stored.  As a result, these objects are not portable
+between R sessions without special handling, which causes problems when
+including them in \code{targets} pipelines with \code{\link[targets:tar_target]{targets::tar_target()}}.
+The functions, \code{\link[=tar_terra_rast]{tar_terra_rast()}}, \code{\link[=tar_terra_sds]{tar_terra_sds()}},
+\code{\link[=tar_terra_sprc]{tar_terra_sprc()}}, \code{\link[=tar_terra_tiles]{tar_terra_tiles()}}, and \code{\link[=tar_terra_vect]{tar_terra_vect()}} handle this
+issue by writing and reading the target as a geospatial file (specified by
+\code{filetype}) rather than saving the relevant object (e.g., \code{SpatRaster},
+\code{SpatVector}, etc.), itself.
 }
 \note{
 The \code{iteration} argument is unavailable because it is hard-coded to
diff --git a/man/tar_terra_sds.Rd b/man/tar_terra_sds.Rd
index 11d8ec1..dbabc5c 100644
--- a/man/tar_terra_sds.Rd
+++ b/man/tar_terra_sds.Rd
@@ -217,6 +217,19 @@ target class "tar_stem" for use in a target pipeline
 Provides a target format for \link[terra:SpatRaster-class]{terra::SpatRasterDataset} objects,
 which hold sub-datasets, each a \code{SpatRaster} that can have multiple layers.
 }
+\details{
+The terra package uses objects like \link[terra:SpatRaster-class]{terra::SpatRaster},
+\link[terra:SpatVector-class]{terra::SpatVector}, and \link[terra:SpatRaster-class]{terra::SpatRasterDataset} (SDS) objects -
+these do not contain the data directly—they contain a C++ pointer to memory
+where the data is stored.  As a result, these objects are not portable
+between R sessions without special handling, which causes problems when
+including them in \code{targets} pipelines with \code{\link[targets:tar_target]{targets::tar_target()}}.
+The functions, \code{\link[=tar_terra_rast]{tar_terra_rast()}}, \code{\link[=tar_terra_sds]{tar_terra_sds()}},
+\code{\link[=tar_terra_sprc]{tar_terra_sprc()}}, \code{\link[=tar_terra_tiles]{tar_terra_tiles()}}, and \code{\link[=tar_terra_vect]{tar_terra_vect()}} handle this
+issue by writing and reading the target as a geospatial file (specified by
+\code{filetype}) rather than saving the relevant object (e.g., \code{SpatRaster},
+\code{SpatVector}, etc.), itself.
+}
 \note{
 The \code{iteration} argument is unavailable because it is hard-coded to
 \code{"list"}, the only option that works currently.
diff --git a/man/tar_terra_sprc.Rd b/man/tar_terra_sprc.Rd
index 973b233..766c474 100644
--- a/man/tar_terra_sprc.Rd
+++ b/man/tar_terra_sprc.Rd
@@ -217,6 +217,19 @@ target class "tar_stem" for use in a target pipeline
 Provides a target format for \link[terra:SpatRaster-class]{terra::SpatRasterCollection} objects,
 which have no restriction in the extent or other geometric parameters.
 }
+\details{
+The terra package uses objects like \link[terra:SpatRaster-class]{terra::SpatRaster},
+\link[terra:SpatVector-class]{terra::SpatVector}, and \link[terra:SpatRaster-class]{terra::SpatRasterDataset} (SDS) objects -
+these do not contain the data directly—they contain a C++ pointer to memory
+where the data is stored.  As a result, these objects are not portable
+between R sessions without special handling, which causes problems when
+including them in \code{targets} pipelines with \code{\link[targets:tar_target]{targets::tar_target()}}.
+The functions, \code{\link[=tar_terra_rast]{tar_terra_rast()}}, \code{\link[=tar_terra_sds]{tar_terra_sds()}},
+\code{\link[=tar_terra_sprc]{tar_terra_sprc()}}, \code{\link[=tar_terra_tiles]{tar_terra_tiles()}}, and \code{\link[=tar_terra_vect]{tar_terra_vect()}} handle this
+issue by writing and reading the target as a geospatial file (specified by
+\code{filetype}) rather than saving the relevant object (e.g., \code{SpatRaster},
+\code{SpatVector}, etc.), itself.
+}
 \note{
 The \code{iteration} argument is unavailable because it is hard-coded to
 \code{"list"}, the only option that works currently.
diff --git a/man/tar_terra_vect.Rd b/man/tar_terra_vect.Rd
index 08ca86f..23e7982 100644
--- a/man/tar_terra_vect.Rd
+++ b/man/tar_terra_vect.Rd
@@ -217,13 +217,17 @@ target class "tar_stem" for use in a target pipeline
 Provides a target format for \link[terra:SpatVector-class]{terra::SpatVector} objects.
 }
 \details{
-\link[terra:SpatVector-class]{terra::SpatVector} objects do not contain vector data directly—they
-contain a C++ pointer to memory where the data is stored.  As a result, these
-objects are not portable between R sessions without special handling, which
-causes problems when including them in \code{targets} pipelines with
-\code{tar_target()}. \code{tar_terra_rast()} handles this issue by writing and reading
-the target as a geospatial file (specified by \code{filetype}) rather than saving
-the \code{SpatVector} object itself.
+The terra package uses objects like \link[terra:SpatRaster-class]{terra::SpatRaster},
+\link[terra:SpatVector-class]{terra::SpatVector}, and \link[terra:SpatRaster-class]{terra::SpatRasterDataset} (SDS) objects -
+these do not contain the data directly—they contain a C++ pointer to memory
+where the data is stored.  As a result, these objects are not portable
+between R sessions without special handling, which causes problems when
+including them in \code{targets} pipelines with \code{\link[targets:tar_target]{targets::tar_target()}}.
+The functions, \code{\link[=tar_terra_rast]{tar_terra_rast()}}, \code{\link[=tar_terra_sds]{tar_terra_sds()}},
+\code{\link[=tar_terra_sprc]{tar_terra_sprc()}}, \code{\link[=tar_terra_tiles]{tar_terra_tiles()}}, and \code{\link[=tar_terra_vect]{tar_terra_vect()}} handle this
+issue by writing and reading the target as a geospatial file (specified by
+\code{filetype}) rather than saving the relevant object (e.g., \code{SpatRaster},
+\code{SpatVector}, etc.), itself.
 }
 \note{
 The \code{iteration} argument is unavailable because it is hard-coded to