diff --git a/NEWS.md b/NEWS.md
index 8f2e1f1..351de6b 100644
--- a/NEWS.md
+++ b/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
diff --git a/R/build.R b/R/build.R
index 4457b11..0c03dbf 100644
--- a/R/build.R
+++ b/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
diff --git a/man/build.Rd b/man/build.Rd
index 5e0ad5f..31544a7 100644
--- a/man/build.Rd
+++ b/man/build.Rd
@@ -35,12 +35,14 @@ If \code{NULL}, it defaults to the parent directory of the package.}
 \item{vignettes, manual}{For source packages: if \code{FALSE}, don't build PDF
 vignettes (\code{--no-build-vignettes}) or manual (\code{--no-manual}).}
 
-\item{clean_doc}{If \code{TRUE}, clean the files in \code{inst/doc} before building
-the package. If \code{NULL} and the \code{Config/build/clean-inst-doc} entry is
-present in \code{DESCRIPTION}, then that is used. Otherwise, if \code{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.}
+\item{clean_doc}{If \code{TRUE}, clean the existing documents by deleting the
+entire \code{inst/doc} directory before building the package. If \code{FALSE},
+leave \code{inst/doc} untouched. If \code{NULL}
+(the default), first the \code{Config/build/clean-inst-doc} entry in
+\code{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.}
 
 \item{args}{An optional character vector of additional command
 line arguments to be passed to \verb{R CMD build} if \code{binary = FALSE},