clean_doc description in build help is incomplete

[RossBoylan]

The description reads

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.

This does not specify what happens if the parameter is FALSE.

It doesn't say what happens if NULL in the non-interactive case, though it suggests that would delete. And the code seems to confirm that.

I expect that if it's FALSE inst/doc is left alone with no further prompting, regardless of the setting in DESCRIPTION or the state of interactivity. By inspection, that looks like what the code currently does.

Possible Alternate Wording

If TRUE (or anything that tests as TRUE) delete install/doc and all files in it before building the package. If FALSE (or any non-NULL equivalent), skip the deletion. If NULL and the Config/build/clean-inst-doc entry is present in DESCRIPTION, then that is used. If the value is still NULL and the session is interactive, the user is prompted for what to do. If the session is not interactive, the directory is deleted, i.e., the value is treated as TRUE.

Note the use of "delete" rather than the existing "clean"; I think it more clearly conveys what's going on.

Related

As noted in #186, the current behavior on interactively selected No is not the same as FALSE, since the interactive route aborts the build. My wording is based on what I think the intended behavior is.