Clarify labelled vectors in read docs

NEWS.md

@@ -1,5 +1,10 @@
 # haven (development version)
 
+* Documentation for `read_*()` functions now more clearly explains that
+  labelled vectors are an intermediate representation, and points users to
+  `as_factor()` and `zap_labels()` when preparing imported categorical
+  variables for analysis (#741).
+
 * `col_select` in the `read_*()` functions now correctly implements the
   tidyselect interface. Columns will be returned in the order specified in
   `col_select` and can be renamed, e.g. `col_select = c(new = old)` (#685).

R/haven-sas.R

@@ -27,6 +27,13 @@
 #'   Variable labels are stored in the "label" attribute of each variable. It is
 #'   not printed on the console, but the RStudio viewer will show it.
 #'
+#'   Value labels from a catalog file are preserved with the [labelled()] class.
+#'   Labelled vectors are an intermediate representation that preserves the
+#'   original value labels, not a regular R factor. Convert labelled categorical
+#'   variables with [as_factor()], or remove value labels with [zap_labels()] if
+#'   you need plain R vectors for analysis. See `vignette("semantics")` for more
+#'   details.
+#'
 #' @export
 #' @examples
 #' path <- system.file("examples", "iris.sas7bdat", package = "haven")

R/haven-spss.R

@@ -21,6 +21,13 @@
 #'   Variable labels are stored in the "label" attribute of each variable.
 #'   It is not printed on the console, but the RStudio viewer will show it.
 #'
+#'   Value labels are preserved with the [labelled()] class, or
+#'   [labelled_spss()] when `user_na = TRUE`. Labelled vectors are an
+#'   intermediate representation that preserves the original value labels, not a
+#'   regular R factor. Convert labelled categorical variables with [as_factor()],
+#'   or remove value labels with [zap_labels()] if you need plain R vectors for
+#'   analysis. See `vignette("semantics")` for more details.
+#'
 #'   `write_sav()` returns the input `data` invisibly.
 #' @name read_spss
 #' @examples

R/haven-stata.R

@@ -59,6 +59,12 @@
 #'   Variable labels are stored in the "label" attribute of each variable.
 #'   It is not printed on the console, but the RStudio viewer will show it.
 #'
+#'   Value labels are preserved with the [labelled()] class. Labelled vectors are
+#'   an intermediate representation that preserves the original value labels,
+#'   not a regular R factor. Convert labelled categorical variables with
+#'   [as_factor()], or remove value labels with [zap_labels()] if you need plain
+#'   R vectors for analysis. See `vignette("semantics")` for more details.
+#'
 #'   If a dataset label is defined in Stata, it will stored in the "label"
 #'   attribute of the tibble.
 #'