be more elaborate with return value documentation, especially for as.…

…data.frame()

R/fcwt.R

@@ -60,6 +60,8 @@
 #' @return
 #'  The spectogram, a numeric real-valued matrix with dimensions
 #'  `dim = c(length(signal), n_freqs)`.
+#'  This matrix is wrapped into a S3-class `fcwtr_scalogram` so that plotting and
+#'  coercion functions can be used conveniently.
 #'
 #' @examples
 #' ts_sin_440 <- sin((1:5000) * 2 * pi * 440 / 44100)

R/fcwtr_scalogram.R

@@ -121,11 +121,23 @@ rm_na_time_slices <- function(x) {
 #'
 #' Internally, the scalogram resulting from [fcwt()] is represented by
 #' a numeric matrix. This method coerces this matrix into a reasonable
-#' data frame. It is associated to a certain runtime cost.
+#' data frame. Note that this conversion has a significant run time cost.
 #'
 #' @param x
 #'  An object resulting from [fcwt()].
 #'
+#' @return
+#'  A [data.frame()] object representing the scalogram data with four columns:
+#' \describe{
+#'   \item{time_ind}{An integer index uniquely identifying time slices.}
+#'   \item{time}{The time difference to the first time slice in physical units.
+#'               The time unit is the inverse of the frequency unit chosen by the user
+#'               for the `sample_freq` argument of [fcwt()].}
+#'   \item{freq}{The frequency in the same units as the `sample_freq` argument
+#'               of [fcwt()].}
+#'   \item{value}{The fCWT result for the particular time-frequency combination.}
+#' }
+#'
 #' @inheritParams base::as.data.frame
 #' @export
 as.data.frame.fcwtr_scalogram <- function(x, ...) {
@@ -136,7 +148,7 @@ as.data.frame.fcwtr_scalogram <- function(x, ...) {
 
   df[["time"]] <- df[["time_ind"]] / attr(x, "sample_freq")
 
-  df
+  df[, c("time_ind", "time", "freq", "value")]
 }
 
 #' Scalogram plotting
@@ -148,6 +160,7 @@ as.data.frame.fcwtr_scalogram <- function(x, ...) {
 #'  An object resulting from [fcwt()].
 #'
 #' @inheritParams autoplot.fcwtr_scalogram
+#' @return No return value, called for side effects.
 #'
 #' @importFrom graphics plot
 #' @export