[nongnu] elpa/bind-map c8fa049b70 13/97: Update Commentary section to match README

[ELPA Syncer]

branch: elpa/bind-map
commit c8fa049b7099bc9e0270b929216c020a77200c2f
Author: justbur <justin@burkett.cc>
Commit: justbur <justin@burkett.cc>

    Update Commentary section to match README
---
 bind-map.el | 49 +++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/bind-map.el b/bind-map.el
index 7561080232..fd2a27d143 100644
--- a/bind-map.el
+++ b/bind-map.el
@@ -23,11 +23,12 @@
 
 ;;; Commentary:
 
-;; Provides the macro `bind-map' which can be used to make a keymap available
-;; across different "leader keys" including ones tied to evil states. It is
-;; essentially a generalization of the idea of a leader key as used in vim or
-;; the Emacs evil-leader package. This is probably best explained with an
-;; example.
+;; bind-map is an Emacs package providing the macro `bind-map' which can be 
used
+;; to make a keymap available across different "leader keys" including ones 
tied
+;; to evil states. It is essentially a generalization of the idea of a leader
+;; key as used in vim or the Emacs https://github.com/cofi/evil-leader package,
+;; and allows for an arbitrary number of "leader keys". This is probably best
+;; explained with an example.
 
 ;; (bind-map my-lisp-map
 ;;   :keys ("M-m")
@@ -37,11 +38,14 @@
 ;;                 lisp-interaction-mode
 ;;                 lisp-mode))
 
-;; This will take my-lisp-map and make it available under M-m or SPC (in evil's
-;; normal or visual state. See `bind-map-default-evil-states' for the 
defaults.)
-;; when one of the specified major mode is active (there is no need to make 
sure
-;; the respective modes' packages are loaded before this declaration). See the
-;; docstring of `bind-map' for more options.
+;; This will take my-lisp-map and make it available under the prefixes (or
+;; leaders) M-m and SPC, where the latter is only bound in evil's normal or
+;; visual state (defaults in `bind-map-default-evil-states') when one of the
+;; specified major mode is active (there is no need to make sure the respective
+;; modes' packages are loaded before this declaration). It is also possible to
+;; make the bindings conditional on minor modes being loaded, or a mix of major
+;; and minor modes. If no modes are specified, the relevant global maps are
+;; used. See the docstring of `bind-map' for more options.
 
 ;; The idea behind this package is that you want to organize your personal
 ;; bindings in a series of keymaps separate from built-in mode maps. You can
@@ -49,6 +53,31 @@
 ;; and a declaration like the one above will take care of ensuring that these
 ;; bindings are available in the correct places.
 
+;; Binding keys in the maps
+
+;; You may use the built-in `define-key' which will function as intended.
+;; `bind-key' (part of https://github.com/jwiegley/use-package) is another
+;; option. For those who want a different interface, the following functions 
are
+;; also provided, which both just use `define-key' internally, but allow for
+;; multiple bindings without much syntax.
+
+;; (bind-map-set-keys my-lisp-map
+;;   "c" 'compile
+;;   "C" 'check
+;;   ;; ...
+;;   )
+;; (bind-map-set-key-defaults my-lisp-map
+;;   "c" 'compile
+;;   "C" 'check
+;;   ;; ...
+;;   )
+
+;; The second function only adds the bindings if there is no existing binding
+;; for that key. It is probably only useful for shared configurations, where 
you
+;; want to provide a default binding but don't want that binding to overwrite
+;; one made by the user. Note the keys in both functions are strings that are
+;; passed to `kbd' before binding them.
+
 ;;; Code:
 
 (require 'cl-lib)