Fully document clean_doc behavior in build()

NEWS.md

@@ -1,5 +1,9 @@
 # pkgbuild (development version)
 
+* The documentation for the `clean_doc` argument of `build()` now fully
+  describes the behavior for `TRUE`, `FALSE`, and `NULL`, including the
+  non-interactive case (@jimhester, #187).
+
 * `needs_compile()` now ignores `.gcov` code coverage files.
 
 # pkgbuild 1.4.8

R/build.R

@@ -100,12 +100,14 @@
 #'   register routines with
 #'   `tools::package_native_routine_registration_skeleton()` before building
 #'   the package. It is ignored if package does not need compilation.
-#' @param clean_doc If `TRUE`, clean the files in `inst/doc` before building
-#'   the package. If `NULL` and the `Config/build/clean-inst-doc` entry is
-#'   present in `DESCRIPTION`, then that is used. Otherwise, if `NULL`,
-#'   and interactive, ask to remove the files prior to cleaning. In most
-#'   cases cleaning the files is the correct behavior to avoid stale
-#'   vignette outputs in the built package.
+#' @param clean_doc If `TRUE`, clean the existing documents by deleting the
+#'   entire `inst/doc` directory before building the package. If `FALSE`,
+#'   leave `inst/doc` untouched. If `NULL`
+#'   (the default), first the `Config/build/clean-inst-doc` entry in
+#'   `DESCRIPTION` is used if present, otherwise if the session is
+#'   interactive the user is prompted for what to do, if non-interactive
+#'   the directory is deleted. In most cases cleaning the files is the
+#'   correct behavior to avoid stale vignette outputs in the built package.
 #' @export
 #' @return a string giving the location (including file name) of the built
 #'  package