; Improve use-package Commentary sections

* lisp/use-package/bind-key.el:
* lisp/use-package/use-package-bind-key.el:
* lisp/use-package/use-package-core.el:
* lisp/use-package/use-package-ensure-system-package.el:
* lisp/use-package/use-package-ensure.el:
* lisp/use-package/use-package.el: Improve Commentary sections.

10 files changed, 45 insertions, 29 deletions

diff --git a/lisp/use-package/bind-key.el b/lisp/use-package/bind-key.el
index 52e797b7bb9..9a1d65ba5ef 100644
--- a/lisp/use-package/bind-key.el
+++ b/lisp/use-package/bind-key.el
@@ -27,14 +27,12 @@
 
 ;;; Commentary:
 
-;; If you have lots of keybindings set in your .emacs file, it can be hard to
-;; know which ones you haven't set yet, and which may now be overriding some
-;; new default in a new Emacs version.  This module aims to solve that
-;; problem.
+;; If you have lots of keybindings set in your init file, it can be
+;; hard to know which ones you haven't set yet, and which may now be
+;; overriding some new default in a new Emacs version.  This module
+;; aims to solve that problem.
 ;;
-;; Bind keys as follows in your .emacs:
-;;
-;;   (require 'bind-key)
+;; Bind keys as follows in your init file:
 ;;
 ;;   (bind-key "C-c x" 'my-ctrl-c-x-command)
 ;;
@@ -97,6 +95,8 @@
 ;; This display will tell you if you've overridden a default keybinding, and
 ;; what the default was.  Also, it will tell you if the key was rebound after
 ;; your binding it with `bind-key', and what it was rebound it to.
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
diff --git a/lisp/use-package/use-package-bind-key.el b/lisp/use-package/use-package-bind-key.el
index a9e921a478a..44242c9e01d 100644
--- a/lisp/use-package/use-package-bind-key.el
+++ b/lisp/use-package/use-package-bind-key.el
@@ -26,6 +26,10 @@
 ;; keywords.  Note that these are currently still baked into
 ;; `use-package-keywords' and `use-package-deferring-keywords', although this
 ;; is harmless if they are never used.
+;;
+;; These keywords are made available by default by requiring `use-package'.
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
diff --git a/lisp/use-package/use-package-core.el b/lisp/use-package/use-package-core.el
index edc9fc689df..868a65803a4 100644
--- a/lisp/use-package/use-package-core.el
+++ b/lisp/use-package/use-package-core.el
@@ -22,14 +22,10 @@
 
 ;;; Commentary:
 
-;; The `use-package' declaration macro allows you to isolate package
-;; configuration in your ".emacs" in a way that is performance-oriented and,
-;; well, just tidy.  I created it because I have over 80 packages that I use
-;; in Emacs, and things were getting difficult to manage.  Yet with this
-;; utility my total load time is just under 1 second, with no loss of
-;; functionality!
+;; This file contains the core implementation of the `use-package'
+;; macro.
 ;;
-;; Please see README.md from the same repository for documentation.
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
diff --git a/lisp/use-package/use-package-delight.el b/lisp/use-package/use-package-delight.el
index 7d50e4acda5..41978b94f49 100644
--- a/lisp/use-package/use-package-delight.el
+++ b/lisp/use-package/use-package-delight.el
@@ -22,8 +22,11 @@
 
 ;;; Commentary:
 
-;; Provides support for the :delight keyword, which is made available by
-;; default by requiring `use-package'.
+;; Provides support for the :delight keyword, which is made available
+;; by default by requiring `use-package'.  Using it requires the
+;; `delight' package to be installed (available on GNU ELPA).
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
diff --git a/lisp/use-package/use-package-diminish.el b/lisp/use-package/use-package-diminish.el
index f6c286152d4..7fff93b0e9b 100644
--- a/lisp/use-package/use-package-diminish.el
+++ b/lisp/use-package/use-package-diminish.el
@@ -22,8 +22,11 @@
 
 ;;; Commentary:
 
-;; Provides support for the :diminish keyword, which is made available by
-;; default by requiring `use-package'.
+;; Provides support for the :diminish keyword, which is made available
+;; by default by requiring `use-package'.  Using it requires the
+;; `diminish' package to be installed (available on GNU ELPA).
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
diff --git a/lisp/use-package/use-package-ensure-system-package.el b/lisp/use-package/use-package-ensure-system-package.el
index 867d8a18b4d..6681e5afb72 100644
--- a/lisp/use-package/use-package-ensure-system-package.el
+++ b/lisp/use-package/use-package-ensure-system-package.el
@@ -27,7 +27,11 @@
 ;;; Commentary:
 
 ;; The `:ensure-system-package` keyword allows you to ensure system
-;; binaries exist alongside your `use-package` declarations.
+;; binaries exist alongside your `use-package` declarations.  Using it
+;; requires the `system-packages' package to be installed (available
+;; on GNU ELPA).
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
diff --git a/lisp/use-package/use-package-ensure.el b/lisp/use-package/use-package-ensure.el
index c8f05c4b40e..dae0312dbad 100644
--- a/lisp/use-package/use-package-ensure.el
+++ b/lisp/use-package/use-package-ensure.el
@@ -22,8 +22,10 @@
 
 ;;; Commentary:
 
-;; Provides support for the :ensure and :pin keywords, which is made available
-;; by default by requiring `use-package'.
+;; Provides support for the :ensure and :pin keywords, which are made
+;; available by default by requiring `use-package'.
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
diff --git a/lisp/use-package/use-package-jump.el b/lisp/use-package/use-package-jump.el
index 155c709c535..6fc52afd286 100644
--- a/lisp/use-package/use-package-jump.el
+++ b/lisp/use-package/use-package-jump.el
@@ -22,10 +22,12 @@
 
 ;;; Commentary:
 
-;; Provides the command `M-x use-package-jump-to-package-form', however it
+;; Provides the command `M-x use-package-jump-to-package-form'.  However, it
 ;; only works if the package being jumped to was required during
-;; initialization.  If it was delay-loaded, it will not work.
+;; initialization.  If it was autoloaded, it will not work.
 ;; Improvements are needed.
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
diff --git a/lisp/use-package/use-package-lint.el b/lisp/use-package/use-package-lint.el
index 630b1845a09..498213a76bf 100644
--- a/lisp/use-package/use-package-lint.el
+++ b/lisp/use-package/use-package-lint.el
@@ -23,6 +23,8 @@
 ;;; Commentary:
 
 ;; Provides the command `M-x use-package-lint'.
+;;
+;; See the `use-package' info manual for more information.
 
 ;;; Code:
 
diff --git a/lisp/use-package/use-package.el b/lisp/use-package/use-package.el
index 7becd88e6d3..0929696466b 100644
--- a/lisp/use-package/use-package.el
+++ b/lisp/use-package/use-package.el
@@ -28,13 +28,13 @@
 ;;; Commentary:
 
 ;; The `use-package' declaration macro allows you to isolate package
-;; configuration in your ".emacs" in a way that is performance-oriented and,
-;; well, just tidy.  I created it because I have over 80 packages that I use
-;; in Emacs, and things were getting difficult to manage.  Yet with this
-;; utility my total load time is just under 1 second, with no loss of
-;; functionality!
+;; configuration in your init file in a way that is
+;; performance-oriented and, well, just tidy.  I created it because I
+;; have over 80 packages that I use in Emacs, and things were getting
+;; difficult to manage.  Yet with this utility my total load time is
+;; just under 1 second, with no loss of functionality!
 ;;
-;; Please see README.md from the same repository for documentation.
+;; See the `use-package' info manual for more information.
 
 ;;; Code: