docs: improve documentation

Author: martinctc

R/copy_df.R

@@ -2,30 +2,43 @@
 #' 
 #' This is a pipe-optimised function, and
 #' accompanies read_df() as a tool for ad-hoc analysis, which reads a data table copied from Excel into R.
+#' 
+#' @note This function only works on Windows. On other platforms, it will
+#'   issue a warning and return the input invisibly.
 #'
 #' @param x Data frame to be passed through. Cannot contain list-columns or nested data frames.
 #' @param row.names A logical vector for specifying whether to allow row names. Defaults to FALSE.
 #' @param col.names A logical vector for specifying whether to allow column names. Defaults to FALSE.
 #' @param expand Add number to manually expand clipboard size
 #' @param quietly Set this to TRUE to not print data frame on console
 #' @param ... Additional arguments for write.table().
+#' 
+#' @return Invisibly returns the input data frame `x`.
+#' 
 #' @export
-copy_df <-function(x,row.names=FALSE,
-                   col.names=TRUE,
-                   expand="",quietly=FALSE,...) {
-  expand_x <- stringr::str_remove_all(expand,"-") # For backward compatibility
-  if(expand==""){
-    write.table(x,"clipboard-5000",
-                sep="\t",
-                row.names=row.names,
-                col.names=col.names,...)
+copy_df <- function(x, row.names = FALSE,
+                    col.names = TRUE,
+                    expand = "", quietly = FALSE, ...) {
+  
+ if (.Platform$OS.type != "windows") {
+    warning("copy_df() only works on Windows.", call. = FALSE)
+    return(invisible(x))
+  }
+  
+  expand_x <- stringr::str_remove_all(expand, "-") # For backward compatibility
+  if (expand == "") {
+    write.table(x, "clipboard-5000",
+                sep = "\t",
+                row.names = row.names,
+                col.names = col.names, ...)
   } else {
-    expand_x <- paste0("-",expand_x)
-    write.table(x,paste0("clipboard",expand_x),
-                sep="\t",
-                row.names=row.names,
-                col.names=col.names,
+    expand_x <- paste0("-", expand_x)
+    write.table(x, paste0("clipboard", expand_x),
+                sep = "\t",
+                row.names = row.names,
+                col.names = col.names,
                 ...)
   }
-  if(quietly==FALSE) print(x)
+  if (quietly == FALSE) print(x)
+  invisible(x)
 }

R/cor_to_df.R

@@ -10,6 +10,10 @@
 #' @param cor_m Correlation matrix in the form of an output from cor().
 #' @param label_table A two-column table with one column used for matching and the other for returning labels.
 #' @param id A character vector specifying the name of the matching / id column in the label_table.
+#' 
+#' @return A tibble representation of the correlation matrix, optionally with
+#'   variable labels matched from the label table.
+#'   
 #' @export
 cor_to_df <- function(cor_m, label_table = NULL, id = NULL){
   if(is.null(label_table) | is.null(id)){

R/look_up.R

@@ -5,6 +5,10 @@
 #' @param index Character string of the key/index column used for matching
 #' @param column Column index (integer) or name (string) to return from the lookup table. 
 #' Default is the second column.
+#' 
+#' @return A character vector with matched values from the lookup table, or the original
+#'   values if no match is found.
+#'   
 #' @examples
 #' library(magrittr)
 #' library(dplyr)

R/read_df.R

@@ -1,8 +1,17 @@
-#' Read in a data frame in the clipboard, copied from Excel
+#' Read in a data frame from the clipboard, copied from Excel
+#' 
+#' @note This function only works on Windows. On other platforms, it will
+#'   stop with an error.
 #' 
 #' @param header Logical value to specify whether copied table contains a header row.
 #' @param ... Additional arguments for read.table().
+#' 
+#' @return A data frame containing the clipboard contents.
+#' 
 #' @export
-read_df <- function(header=TRUE,...) {
-  read.table("clipboard",sep="\t",header=header,...)
+read_df <- function(header = TRUE, ...) {
+  if (.Platform$OS.type != "windows") {
+    stop("read_df() only works on Windows.", call. = FALSE)
+  }
+  read.table("clipboard", sep = "\t", header = header, ...)
 }

R/sav_to_rds.R

@@ -7,7 +7,11 @@
 #' 
 #' @param import String containing path to .SAV file
 #' @param export String containing desired file name for RDS export. 
-#' Default is to use same name as .SAV file     
+#' Default is to use same name as .SAV file
+#' 
+#' @return NULL, invisibly. The function is called for its side effect of
+#'   creating an RDS file.
+#'   
 #' @import haven   
 #' @export
 sav_to_rds<-function(import,export=""){

R/set_vall.R

@@ -11,21 +11,24 @@
 #' @family Value labels
 #' @family Labels
 #' 
+#' @return The input variable `x` as a labelled vector with value labels set.
+#' 
 #' @examples 
 #' 
 #' library(magrittr)
 #' library(dplyr)
 #' library(tibble)
-#' tibble(RESPID=1:1000,
-#'        Q1=sample(c(0,1,2),1000,replace=TRUE),
-#'        Q2=sample(c(0,1),1000,replace=TRUE))-> df
+#' tibble(RESPID = 1:1000,
+#'        Q1 = sample(c(0, 1, 2), 1000, replace = TRUE),
+#'        Q2 = sample(c(0, 1), 1000, replace = TRUE)) -> df
 #' df %>%
-#'   mutate_at("Q2",funs(set_varl(.,"What is your answer to this yes/no question?"))) %>%
-#'   mutate_at("Q2",funs(set_vall(.,c("No"=0,"Yes"=1)))) %>%
+#'   mutate(Q2 = set_varl(Q2, "What is your answer to this yes/no question?")) %>%
+#'   mutate(Q2 = set_vall(Q2, c("No" = 0, "Yes" = 1))) %>%
 #'   .$Q2 %>% attributes()
 #' @export
-set_vall <- function(x,value_labels){
+set_vall <- function(x, value_labels) {
   label <- attr(x, 'label')
-  x <- haven::labelled(x,value_labels)
+  x <- haven::labelled(x, value_labels)
   x <- set_varl(x, label)
+  return(x)
 }      

R/set_varl.R

@@ -9,16 +9,18 @@
 #' @family Variable labels
 #' @family Labels
 #' 
+#' @return The input variable `x` with the variable label attribute set.
+#' 
 #' @examples 
 #' library(tibble)
 #' library(dplyr)
 #' library(magrittr)
 #' df <-
-#' tibble(RESPID=1:1000,
-#'        Q1=sample(c(0,1,2),1000,replace=TRUE),
-#'        Q2=sample(c(0,1),1000,replace=TRUE))
+#' tibble(RESPID = 1:1000,
+#'        Q1 = sample(c(0, 1, 2), 1000, replace = TRUE),
+#'        Q2 = sample(c(0, 1), 1000, replace = TRUE))
 #' df %>%
-#'   mutate_at("Q1",funs(set_varl(.,"Which of the following groups do you fall into?"))) %>%
+#'   mutate(Q1 = set_varl(Q1, "Which of the following groups do you fall into?")) %>%
 #'   .$Q1
 #' @export
 set_varl <- function(x, variable_label){

R/superspread.R

@@ -6,6 +6,10 @@
 #' @param select_helpers Uses dplyr-style select functions to select multiple variables. 
 #' Use everything() to select all variables. These variables must all be character type.
 #' @family superspread functions
+#' 
+#' @return A tibble with the original columns plus new dummy variable columns for each
+#'   unique value found in the selected categorical variables.
+#'   
 #' @import dplyr
 #' @importFrom magrittr %>%
 #' @importFrom data.table :=

R/timed_fn.R

@@ -3,6 +3,9 @@
 #' This function generates a character string that suffixes a file name with a time stamp.
 #' @param main The main file name to be used. 
 #' @param extension The file extension to be used, e.g. ".csv"
+#' 
+#' @return A character string with the file name, timestamp, and extension combined.
+#' 
 #' @import stringr
 #' @examples
 #' timed_fn("Q15. ",".xlsx")