Update the documentation for :custom as per #850

README.md

@@ -376,8 +376,12 @@ The documentation string is not mandatory.
 **NOTE**: these are only for people who wish to keep customizations with their
 accompanying use-package declarations. Functionally, the only benefit over
 using `setq` in a `:config` block is that customizations might execute code
-when values are assigned. If you currently use `M-x customize-option` and save
-to a settings file, you do not want to use this option.
+when values are assigned.
+
+**NOTE**: The customized values are **not** saved in the Emacs `custom-file`.
+Thus you should either use the `:custom` option **or** you should use `M-x
+customize-option` which will save customized values in the Emacs `custom-file`.
+Do not use both.
 
 ### Customizing faces
 

use-package-core.el

@@ -1563,7 +1563,9 @@ this file.  Usage:
 :load-path       Add to the `load-path' before attempting to load the package.
 :diminish        Support for diminish.el (if installed).
 :delight         Support for delight.el (if installed).
-:custom          Call `custom-set' or `set-default' with each variable definition.
+:custom          Call `custom-set' or `set-default' with each variable
+                 definition without modifying the Emacs `custom-file'.
+                 (compare with `custom-set-variables').
 :custom-face     Call `customize-set-faces' with each face definition.
 :ensure          Loads the package using package.el if necessary.
 :pin             Pin the package to an archive."