Fixing documentation

R/play-sox.R

@@ -2,7 +2,7 @@
 #'
 #' Plays a sound using the command-line tool sox.
 #'
-#' The sound is synthesised using \code{\link{save_wav_pluck}}
+#' The sound is synthesised using \code{\link{save_wav_sox}}
 #' and saved to a temporary file, which is then played from the R session.
 #'
 #' @note
@@ -11,8 +11,8 @@
 #' must be installed and available on the command line,
 #' making available the commands \code{sox} and \code{play}.
 #'
-#' @param x Object to play (see \code{\link{save_wav_pluck}} for valid options).
-#' @param ... Further parameters to pass to \code{\link{save_wav_pluck}}.
+#' @param x Object to play (see \code{\link{save_wav_sox}} for valid options).
+#' @param ... Further parameters to pass to \code{\link{save_wav_sox}}.
 #'
 #' @export
 play_sox <- function(x, ...) {

R/save-wav-sox.R

@@ -1,6 +1,6 @@
 #' Save wav file (sox)
 #'
-#' Saves object to a wav file using the 'sox' timbre from sox
+#' Saves object to a wav file using sox
 #' (\url{http://sox.sourceforge.net/}).
 #'
 #' @note
@@ -12,36 +12,53 @@
 #' @param x Object to save; methods exist for individual chords
 #' and for vectors of chords (see \code{\link{vec}}).
 #' Chords are coerced to a \code{\link{pi_chord}} representation.
+#'
 #' @param file (Character scalar) Output file.
-#' @param chord_length (Numeric scalar) Length of each output chord, in seconds.
+#'
 #' @param ... Parameters passed to methods.
 #'
+#' @rdname save_wav_sox
 #' @export
 save_wav_sox <- function(x, file, ...) {
   UseMethod("save_wav_sox")
 }
 
 #' @export
-save_wav_sox.default <- function(x, ...) {
-  save_wav_sox(pi_chord(x), ...)
+save_wav_sox.default <- function(x, file, ...) {
+  save_wav_sox(pi_chord(x), file, ...)
 }
 
 #' @export
+#' @rdname save_wav_sox
 save_wav_sox.coded_vec <- function(x, file, ...) {
   save_wav_sox(decode(x), file, ...)
 }
 
 #' @export
-save_wav_sox.pi_chord <- function(x, ...) {
-  save_wav_sox(fr_chord(x), ...)
+#' @rdname save_wav_sox
+save_wav_sox.pi_chord <- function(x, file, ...) {
+  save_wav_sox(fr_chord(x), file, ...)
 }
 
 #' @export
-save_wav_sox.sparse_pi_spectrum <- function(x, ...) {
-  save_wav_sox(sparse_fr_spectrum(x), ...)
+#' @rdname save_wav_sox
+save_wav_sox.sparse_pi_spectrum <- function(x, file, ...) {
+  save_wav_sox(sparse_fr_spectrum(x), file, ...)
 }
 
 #' @export
+#' @rdname save_wav_sox
+#'
+#' @param timbre
+#' (Character scalar)
+#' Timbre to use for synthesizing tones.
+#' Only applies to representations that have not already undergone
+#' harmonic expansion.
+#' This parameter is passed to the \code{type} argument of
+#' the \code{sox synth} command.
+#' Valid values include
+#' sine, square, triangle, sawtooth, trapezium, exp, noise,
+#' tpdfnoise, pinknoise, brownnoise, pluck.
 save_wav_sox.fr_chord <- function(x, file, timbre = "pluck", ...) {
   save_wav_sox(
     .sparse_fr_spectrum(frequency = as.numeric(x),
@@ -53,6 +70,12 @@ save_wav_sox.fr_chord <- function(x, file, timbre = "pluck", ...) {
 }
 
 #' @export
+#' @rdname save_wav_sox
+#'
+#' @param reverb
+#' (Numeric scalar)
+#' Reverberance parameter for \code{sox reverb},
+#' expressed as a percentage.
 save_wav_sox.vec <- function(x, file, reverb = 20, ...) {
   files <- paste("chord-", seq_along(x), "-", sep = "") %>%
     tempfile(fileext = ".wav")
@@ -66,16 +89,41 @@ save_wav_sox.vec <- function(x, file, reverb = 20, ...) {
 }
 
 #' @export
+#' @rdname save_wav_sox
+#'
+#' @param chord_length
+#' (Numeric scalar)
+#' Chord length (seconds).
+#'
+#' @param rise_length
+#' (Numeric scalar)
+#' Chord fade-in time (seconds).
+#'
+#' @param fade_length
+#' (Numeric scalar)
+#' Chord fade-out time (seconds).
+#'
+#' @param spectrum_gain
+#' (Coerced to character scalar)
+#' If "auto", then the chord's audio output is peak-normalised to
+#' a fixed value (using "--norm=-3" in sox).
+#' Other values will be passed directly to the "gain" parameter in sox.
+#'
+#' @param volume
+#' (Numeric scalar)
+#' Amplitude multipler (higher values make the sound louder).
+#' Only relevant when \code{spectrum_gain} is not \code{auto}.
+#'
 save_wav_sox.sparse_fr_spectrum <- function(x,
                                             file,
                                             chord_length = 1,
                                             rise_length = 0.01,
                                             fade_length = 0.01,
                                             timbre = "sine",
-                                            partial_volume = 0.1,
                                             spectrum_gain = "auto",
                                             volume = 0.1,
                                             ...) {
+  stopifnot(length(spectrum_gain) == 1)
   fade_length <- fade_length
   frequencies <- freq(x)
   if (timbre == "pluck" && any(frequencies > 4000))