Flesh out docs for the application-specific overrides.

Moved some of this from the vignette to the manpages where we can
be more technical without bogging down the average reader.

Also added a link to the takane page in the validateObject docs.

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: alabaster.base
 Title: Save Bioconductor Objects To File
-Version: 1.3.21
-Date: 2024-03-05
+Version: 1.3.22
+Date: 2024-03-08
 Authors@R: person("Aaron", "Lun", role=c("aut", "cre"), email="[email protected]")
 License: MIT + file LICENSE
 Description: 

R/altReadObject.R

@@ -12,8 +12,10 @@
 #' If \code{fun} is provided, it is used to define the alternative, and the previous alternative is returned.
 #'
 #' @details
-#' \code{altReadObject} is just a wrapper around \code{\link{readObject}} that responds to any setting of \code{altReadObjectFunction}.
-#' This allows alabaster applications to inject customizations into the reading process, e.g., to add more metadata to particular objects.
+#' By default, \code{altReadObject} is just a wrapper around \code{\link{readObject}}.
+#' However, if \code{altReadObjectFunction} is called, \code{altReadObject} calls the replacement \code{fun} instead.
+#' This allows alabaster applications to inject wholesale or class-specific customizations into the reading process,
+#' e.g., to add more metadata whenever an instance of a particular class is encountered.
 #' Developers of alabaster extensions should use \code{altReadObject} (instead of \code{readObject}) to read child objects when writing their own reading functions,
 #' to ensure that application-specific customizations are respected for the children.
 #'
@@ -32,6 +34,11 @@
 #' we correctly call \code{readObject2} and then ultimately \code{readX2}.
 #' }
 #'
+#' The application-specific \code{fun} is free to do anything it wants as long as it understands the representation.
+#' It is usually most convenient to leverage the existing functionality in \code{\link{readObject}},
+#' but if the application-specific saver in \code{\link{altSaveObject}} does something unusual,
+#' then \code{fun} is responsible for the correct interpretation of any custom representation.
+#'
 #' @author Aaron Lun
 #' @examples
 #' old <- altReadObjectFunction()

R/altSaveObject.R

@@ -12,16 +12,18 @@
 #' If \code{generic} is provided, it is used to define the alternative, and the previous alternative is returned.
 #'
 #' @details
-#' \code{altSaveObject} is just a wrapper around \code{\link{saveObject}} that responds to any setting of \code{altSaveObjectFunction}.
-#' This allows applications to inject customizations into the staging process, e.g., to store more metadata to particular objects.
-#' Developers of alabaster extensions should use \code{altSaveObject} to save child objects when writing their \code{saveObject} methods,
+#' By default, \code{altSaveObject} is just a wrapper around \code{\link{saveObject}}.
+#' However, if \code{altSaveObjectFunction} is called, \code{altSaveObject} calls the replacement \code{generic} instead.
+#' This allows alabaster applications to inject wholesale or class-specific customizations into the saving process,
+#' e.g., to save more metadata whenever an instance of a particular class is encountered.
+#' Developers of alabaster extensions should use \code{altSaveObject} to save child objects when implementing \code{saveObject} methods,
 #' to ensure that application-specific customizations are respected for the children.
 #'
 #' To motivate the use of \code{altSaveObject}, consider the following scenario.
 #' \enumerate{
 #' \item We have created a staging method for class X, defined for the \code{\link{saveObject}} generic.
 #' \item An alabaster application Y requires the addition of some custom metadata during the staging process for X.
-#' It defines an alternative staging generic \code{saveObject2} that, upon encountering an instance of X, redirects to a application-specific method.
+#' It defines an alternative staging generic \code{saveObject2} that, upon encountering an instance of X, redirects to an application-specific method (i.e., \code{saveObject2,X-method}).
 #' For example, the \code{saveObject2} method for X could call X's \code{saveObject} method and add the necessary metadata to the result.
 #' \item When operating in the context of application Y, the \code{saveObject2} generic is used to set \code{altSaveObjectFunction}.
 #' Any calls to \code{altSaveObject} in Y's context will subsequently call \code{saveObject2}.
@@ -30,6 +32,11 @@
 #' This ensures that, if a child instance of X is encountered \emph{and} we are operating in the context of application Y, 
 #' we correctly call \code{saveObject2} and then ultimately the application-specific method.
 #' }
+#'
+#' The application-specific \code{generic} is free to do anything it wants as long as the custom representation is understood by the application-specific reader in \code{\link{altReadObject}}.
+#' However, it is usually most convenient to re-use the existing representations created by \code{\link{saveObject}}.
+#' This means that any customizations should not interfere with the validity of those representations, as defined by the \pkg{takane} specifications and enforced by \code{\link{validateObject}}.
+#' We recommend that any customizations should manifest as new files starting with an underscore, as this will not interfere by any \pkg{takane} file specification.
 #' 
 #' @author Aaron Lun
 #' @examples

R/validateObject.R

@@ -1,6 +1,6 @@
 #' Validate an object's on-disk representation
 #'
-#' Validate an object's on-disk representation.
+#' Validate an object's on-disk representation against the \pkg{takane} specifications.
 #' This is done by dispatching to an appropriate validation function based on the type in the \code{OBJECT} file.
 #'
 #' @param path String containing a path to a directory, itself created with a \code{\link{saveObject}} method.
@@ -26,6 +26,9 @@
 #' For the \code{register*} functions, the supplied \code{fun} is added to the corresponding registry for \code{type}.
 #' If \code{fun = NULL}, any existing entry for \code{type} is removed.
 #'
+#' @seealso
+#' \url{https://github.com/ArtifactDB/takane}, for detailed specifications of the on-disk representation for various Bioconductor objects.
+#'
 #' @author Aaron Lun
 #' @examples
 #' library(S4Vectors)

vignettes/userguide.Rmd

@@ -290,9 +290,6 @@ readForApplication(tmp)
 ```
 
 By overriding the saving and reading process for one or more classes, each application can customize the behavior of _alabaster_ to their own needs.
-Any customization is allowed though applications should generally avoid modifying the files created by `saveObject()` as these must follow the **takane** format specifications 
-(unless the application maintainer really knows what they're doing and can perform the modification without violating the relevant specifications).
-If new files must be created, applications may write to any path starting with an underscore as this will not interfere by any specification.
 
 # Session information {-}