[nongnu] elpa/treeview 34ecd7a320 24/25: Fixed issues detected by flycheck; updated documentation

[ELPA Syncer]

branch: elpa/treeview
commit 34ecd7a320dac70d9723f932b3842cfb204a1448
Author: Tilman Rassy <tilman.rassy@googlemail.com>
Commit: Tilman Rassy <tilman.rassy@googlemail.com>

    Fixed issues detected by flycheck; updated documentation
---
 README.md   | 20 +++++++++++++-------
 treeview.el | 41 +++++++++++++++++++++++++++--------------
 2 files changed, 40 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index ab555f6a54..c18ac88665 100644
--- a/README.md
+++ b/README.md
@@ -37,12 +37,15 @@ where the elements have the following meaning:
 Node properties are implemented as plists with Lisp symbols as keys.  The 
following
 properties exist:
 
-  *  `:label-overlay`    &nbsp;&ndash;&nbsp; The overlay containing the node 
label
-  *  `:control-overlay`  &nbsp;&ndash;&nbsp; The overlay containing the node 
control
-  *  `:icon-overlay`     &nbsp;&ndash;&nbsp; The overlay containing the node 
icon
-  *  `:start`            &nbsp;&ndash;&nbsp; A marker at the position where 
the node begins
-  *  `:end`              &nbsp;&ndash;&nbsp; A marker at the position where 
the node ends
-  *  `:state`            &nbsp;&ndash;&nbsp; The state of the node.  See below 
for details
+  *  `node-line-overlay` &nbsp;&ndash;&nbsp; The overlay containing the node 
line
+  *  `indent-overlay`    &nbsp;&ndash;&nbsp; The overlay containing the node 
indentation
+  *  `label-overlay`     &nbsp;&ndash;&nbsp; The overlay containing the node 
label
+  *  `control-overlay`   &nbsp;&ndash;&nbsp; The overlay containing the node 
control
+  *  `icon-overlay`      &nbsp;&ndash;&nbsp; The overlay containing the node 
icon
+  *  `start`             &nbsp;&ndash;&nbsp; A marker at the position where 
the node begins
+  *  `end`               &nbsp;&ndash;&nbsp; A marker at the position where 
the node ends
+  *  `state`             &nbsp;&ndash;&nbsp; The state of the node.  See below 
for details
+  *  `selected`          &nbsp;&ndash;&nbsp; Whether the node is selected 
(non-nil if selected, nil if not)
 
 Node states: Each node is in exactly one of three states, which are 
represented by the
 following Lisp symbols:
@@ -60,7 +63,8 @@ The framework declares a couple of "abstract" functions in 
the sense of function
 variables whose values are function symbols. If the framework is applied for a 
particular purpose,
 specific implementations for these functions must be provided.  Here is a list 
of that function
 variables:
-
+  
+  *  treeview-get-root-node-function
   *  treeview-node-leaf-p-function
   *  treeview-update-node-children-function
   *  treeview-after-node-expanded-function
@@ -78,6 +82,8 @@ variables:
   *  treeview-get-indent-face-function
   *  treeview-get-control-face-function
   *  treeview-get-control-mouse-face-function
+  *  treeview-get-selected-node-face-function
+  *  treeview-get-highlighted-node-face-function
   *  treeview-get-label-keymap-function
   *  treeview-get-label-face-function
   *  treeview-get-label-mouse-face-function
diff --git a/treeview.el b/treeview.el
index 752a1c6b31..beeaedc528 100644
--- a/treeview.el
+++ b/treeview.el
@@ -86,6 +86,9 @@
 ;;
 ;;   state  The state of the node.  See below for details
 ;;
+;;   selected
+;;          Whether the node is selected (non-nil if selected, nil if not)
+;;
 ;; Node states: Each node is in exactly one of three states, which are 
represented by the
 ;; following Lisp symbols:
 ;;
@@ -121,6 +124,8 @@
 ;;   treeview-get-indent-face-function
 ;;   treeview-get-control-face-function
 ;;   treeview-get-control-mouse-face-function
+;;   treeview-get-selected-node-face-function
+;;   treeview-get-highlighted-node-face-function
 ;;   treeview-get-label-keymap-function
 ;;   treeview-get-label-face-function
 ;;   treeview-get-label-mouse-face-function
@@ -464,8 +469,8 @@ The default implementation is `treeview-return-nil'.")
 
 (defvar treeview-get-selected-node-face-function 'treeview-return-nil
   "Function to get the face of selected nodes.
-Called with one argument, the node.  The return value must be a face or nil.  
If a
-face, it is used to highlight selected nodes.
+Called with one argument, the node.  The return value must be a face or nil.
+If a face, it is used to highlight selected nodes.
 
 The default implementation is `treeview-return-nil'.")
 
@@ -478,8 +483,8 @@ The default implementation is `treeview-return-nil'.")
 
 (defvar treeview-get-highlighted-node-face-function 'treeview-return-nil
   "Function to get the face to highlighted a node.
-Called with one argument, the node.  The return value must be a face or nil.  
If a
-face, it is used to highlight the node.
+Called with one argument, the node.  The return value must be a face or nil.
+If a face, it is used to highlight the node.
 
 The default implementation is `treeview-return-nil'.")
 
@@ -558,8 +563,10 @@ CALLBACK should be a function expecting a node as 
argument."
   (treeview-apply-recursively (treeview-get-root-node) callback))
 
 (defun treeview-filter-nodes (filter)
-  "Return a list of all nodes for which FILTER returns non-nil.
-FILTER must be function accepting a node as argument."
+  "Return a list of all nodes accepted by FILTER.
+FILTER must be function expecting a node as argument.  A node is said to be
+accepted by FILTER if FILTER returns a non-nil value when applied to the
+node."
   (let ( (nodes ()) )
     (treeview-for-each-node (lambda (node) (when (funcall filter node) (push 
node nodes))))
     nodes))
@@ -685,11 +692,11 @@ of the overlay, respectively (see overlay documentation 
in the Emacs Lisp refere
 
 (defun treeview-add-face (base-face face-to-add)
   "Add FACE-TO-ADD to BASE-FACE.
-This is an auxiliary function to create face lists for overlays.  BASE-FACE
-should be a face or a list of faces.  FACE-TO-ADD should be a face.  If
-BASE-FACE is a single face, the return value is the list (FACE-TO-ADD 
BASE-FACE).
-If BASE-FACE is a list of faces (FACE1 FACE2 ...), the return value is the list
-(FACE-TO-ADD FACE1 FACE2 ...)."
+This is an auxiliary function to create face lists for overlays.
+BASE-FACE should be a face or a list of faces.  FACE-TO-ADD should be a face.
+If BASE-FACE is a single face, the return value is the list
+\(FACE-TO-ADD BASE-FACE).  If BASE-FACE is a list of faces (FACE1 FACE2 ...),
+the return value is the list (FACE-TO-ADD FACE1 FACE2 ...)."
   (if (listp base-face)
       (unless (memq face-to-add base-face) (setq base-face (cons face-to-add 
base-face)))
     (unless (eq base-face face-to-add) (setq base-face (list face-to-add 
base-face))))
@@ -1186,6 +1193,9 @@ node is removed.  If the node isn't selected, does 
nothing"
   (dolist (node (treeview-get-all-selected-nodes)) (treeview-unselect-node 
node)))
 
 (defun treeview-unselect-all-nodes-after-keyboard-quit ()
+  "Unselect all nodes if `this-command' is `keyboard-quit'.
+If this function is added to `post-command-hook', the selections are revoked
+when \\<global-map> \\[keyboard-quit] is pressed."
   (when (eq this-command 'keyboard-quit) (treeview-unselect-all-nodes)))
 
 (defun treeview-toggle-select-node (node)
@@ -1218,7 +1228,7 @@ For example, if you have nodes
   NODE_3 *
   NODE_4
   NODE_5
-  NODE_6 
+  NODE_6
 
 which are all siblings of each other, and * denotes selection, and NODE is
 NODE_6, then the result is the following:
@@ -1246,7 +1256,7 @@ If there is no selected sibling above nOE, does nothing."
         (when nodes-to-select (dolist (elem nodes-to-select) 
(treeview-select-node elem))) )) ))
 
 (defun treeview-select-gap-above-node-at-point ()
-  "Select all nodes between the node at point and the nearest selected node 
above.
+  "Select all nodes from the node at point to the nearest selected node above.
 The node at point is also selected.
 See `treeview-select-gap-above-node' for more information."
   (interactive)
@@ -1254,7 +1264,7 @@ See `treeview-select-gap-above-node' for more 
information."
     (when node (treeview-select-gap-above-node node))))
 
 (defun treeview-select-gap-above-node-at-event (event)
-  "Select all nodes between the node at EVENT and the nearest selected node 
above.
+  "Select all nodes from the node at EVENT to the nearest selected node above.
 The node at EVENT is also selected.  EVENT should be a mouse event.
 See `treeview-select-gap-above-node' for more information."
   (interactive "@e")
@@ -1262,12 +1272,15 @@ See `treeview-select-gap-above-node' for more 
information."
     (when node (treeview-select-gap-above-node node))))
 
 (defun treeview-unhighlight-node ()
+  "Unhighlight the highlightwd node.
+If there is no highlightwd node, does nothing."
   (when treeview-highlighted-node
     (let ( (node treeview-highlighted-node) )
       (treeview-remove-node-label-face node (funcall 
treeview-get-highlighted-node-face-function node)))
     (setq treeview-highlighted-node nil)))
 
 (defun treeview-highlight-node (node)
+  "Highlight NODE."
   (treeview-unhighlight-node)
   (treeview-add-node-label-face node (funcall 
treeview-get-highlighted-node-face-function node))
   (setq treeview-highlighted-node node))