branch: master
commit 568f3cd9a83f5f5bcb4b379cdba2552a49c913be
Author: Alexey Veretennikov <alexey.veretenni...@afconsult.com>
Commit: Alexey Veretennikov <alexey.veretenni...@afconsult.com>
Fixed checkdoc comments
---
ztree-diff-model.el | 43 +++++++++++----
ztree-diff.el | 58 +++++++++++++-------
ztree-dir.el | 10 ++-
ztree-pkg.el | 9 +++
ztree-util.el | 26 +++++----
ztree-view.el | 155 ++++++++++++++++++++++++++++++++-------------------
6 files changed, 197 insertions(+), 104 deletions(-)
diff --git a/ztree-diff-model.el b/ztree-diff-model.el
index a7153fc..97b5089 100644
--- a/ztree-diff-model.el
+++ b/ztree-diff-model.el
@@ -32,11 +32,12 @@
(require 'ztree-util)
(defvar ztree-diff-model-wait-message nil
- "Message showing while constructing the diff tree")
+ "Message showing while constructing the diff tree.")
(make-variable-buffer-local 'ztree-diff-model-wait-message)
(defun ztree-diff-model-update-wait-message ()
+ "Update the wait mesage with one more '.' progress indication."
(when ztree-diff-model-wait-message
(setq ztree-diff-model-wait-message (concat ztree-diff-model-wait-message
"."))
(message ztree-diff-model-wait-message)))
@@ -54,6 +55,7 @@
(defrecord ztree-diff-node (parent left-path right-path short-name
right-short-name children different))
(defun ztree-diff-node-to-string (node)
+ "Construct the string with contents of the NODE given."
(let* ((string-or-nil #'(lambda (x) (if x
(cond ((stringp x) x)
((eq x 'new) "new")
@@ -79,12 +81,15 @@
(defun ztree-diff-node-short-name-wrapper (node &optional right-side)
+ "Return the short name of the NODE given.
+If the RIGHT-SIDE is true, take the right leaf"
(if (not right-side)
(ztree-diff-node-short-name node)
(ztree-diff-node-right-short-name node)))
(defun ztree-diff-node-is-directory (node)
+ "Determines if the NODE is a directory."
(let ((left (ztree-diff-node-left-path node))
(right (ztree-diff-node-right-path node)))
(if left
@@ -92,12 +97,17 @@
(file-directory-p right))))
(defun ztree-diff-node-side (node)
+ "Determine the side there the file is present for NODE.
+Return BOTH if the file present on both sides;
+LEFT if only on the left side and
+RIGHT if only on the right side."
(let ((left (ztree-diff-node-left-path node))
(right (ztree-diff-node-right-path node)))
(if (and left right) 'both
(if left 'left 'right))))
(defun ztree-diff-node-equal (node1 node2)
+ "Determines if NODE1 and NODE2 are equal."
(and (string-equal (ztree-diff-node-short-name node1)
(ztree-diff-node-short-name node2))
(string-equal (ztree-diff-node-left-path node1)
@@ -106,17 +116,19 @@
(ztree-diff-node-right-path node1))))
(defun ztree-diff-untrampify-filename (file)
- "Returns `file' as the local file name."
+ "Return FILE as the local file name."
(require 'tramp)
(if (not (tramp-tramp-file-p file))
file
(tramp-file-name-localname (tramp-dissect-file-name file))))
(defun ztree-diff-modef-quotify-string (x)
+ "Surround string X with quotes."
(concat "\"" x "\""))
(defun ztree-diff-model-files-equal (file1 file2)
- "Compare files using external diff. Returns t if equal"
+ "Compare files FILE1 and FILE2 using external diff.
+Returns t if equal."
(let* ((file1-untrampified (ztree-diff-untrampify-filename
(ztree-diff-modef-quotify-string file1)))
(file2-untrampified (ztree-diff-untrampify-filename
(ztree-diff-modef-quotify-string file2)))
(diff-command (concat "diff -q" " " file1-untrampified " "
file2-untrampified))
@@ -124,13 +136,15 @@
(not (> (length diff-output) 2))))
(defun ztree-directory-files (dir)
- "Returns the list of full paths of files in a directory, filtering out . and
.."
+ "Return the list of full paths of files in a directory DIR.
+Filters out . and .."
(ztree-filter #'(lambda (file) (let ((simple-name (file-short-name file)))
(not (or (string-equal simple-name ".")
(string-equal simple-name "..")))))
(directory-files dir 'full)))
(defun ztree-diff-model-partial-rescan (node)
+ "Rescan the NODE."
;; assuming what parent is always exists
;; otherwise the UI shall force the full rescan
(let ((parent (ztree-diff-node-parent node))
@@ -141,7 +155,7 @@
(when (and left right
(file-exists-p left)
(file-exists-p right))
- (if isdir
+ (if isdir
(let ((traverse (ztree-diff-node-traverse
node
left
@@ -156,7 +170,8 @@
'diff))))))
(defun ztree-diff-model-subtree (parent path side)
- "Creates a subtree for the given path for either 'left or 'right sides"
+ "Create a subtree with given PARENT for the given PATH.
+Argument SIDE either 'left or 'right side."
(let ((files (ztree-directory-files path))
(result nil))
(dolist (file files)
@@ -184,6 +199,7 @@
result))
(defun ztree-diff-node-update-diff-from-children (node)
+ "Set the diff status for the NODE based on its children."
(let ((children (ztree-diff-node-children node))
(diff nil))
(dolist (child children)
@@ -194,12 +210,14 @@
(ztree-diff-node-set-different node diff)))
(defun ztree-diff-node-update-all-parents-diff (node)
+ "Recursively update all parents diff status for the NODE."
(let ((parent node))
(while (setq parent (ztree-diff-node-parent parent))
(ztree-diff-node-update-diff-from-children parent))))
(defun ztree-diff-model-update-diff (old new)
+ "Get the diff status depending if OLD or NEW is not nil."
(if new
(if (or (not old)
(eq old 'new))
@@ -208,9 +226,10 @@
old))
(defun ztree-diff-node-traverse (parent path1 path2)
- "Function traversing 2 paths returning the list where the
+ "Traverse 2 paths creating the list nodes with PARENT defined and diff
status.
+Function traversing 2 paths PATH1 and PATH2 returning the list where the
first element is the difference status (nil, 'diff, 'new') and
-the rest is the combined list of nodes"
+the rest is the combined list of nodes."
(let ((list1 (ztree-directory-files path1))
(list2 (ztree-directory-files path2))
(different-dir nil)
@@ -218,7 +237,7 @@ the rest is the combined list of nodes"
(ztree-diff-model-update-wait-message)
;; first - adding all entries from left directory
(dolist (file1 list1)
- ;; for every entry in the first directory
+ ;; for every entry in the first directory
;; we are creating the node
(let* ((simple-name (file-short-name file1))
(isdir (file-directory-p file1))
@@ -265,7 +284,7 @@ the rest is the combined list of nodes"
;; second - adding entries from the right directory which are not present
;; in the left directory
(dolist (file2 list2)
- ;; for every entry in the second directory
+ ;; for every entry in the second directory
;; we are creating the node
(let* ((simple-name (file-short-name file2))
(isdir (file-directory-p file2))
@@ -293,12 +312,13 @@ the rest is the combined list of nodes"
(cons different-dir result)))
(defun ztree-diff-model-create (dir1 dir2)
+ "Create a node based on DIR1 and DIR2."
(when (not (file-directory-p dir1))
(error "Path %s is not a directory" dir1))
(when (not (file-directory-p dir2))
(error "Path %s is not a directory" dir2))
(setq ztree-diff-model-wait-message (concat "Comparing " dir1 " and " dir2 "
..."))
- (let* ((model
+ (let* ((model
(ztree-diff-node-create nil dir1 dir2
(file-short-name dir1)
(file-short-name dir2)
@@ -311,6 +331,7 @@ the rest is the combined list of nodes"
model))
(defun ztree-diff-model-update-node (node)
+ "Refresh the NODE."
(setq ztree-diff-model-wait-message
(concat "Updating " (ztree-diff-node-short-name node) " ..."))
(let ((traverse (ztree-diff-node-traverse node
diff --git a/ztree-diff.el b/ztree-diff.el
index 03b1c6c..a421c88 100644
--- a/ztree-diff.el
+++ b/ztree-diff.el
@@ -31,8 +31,8 @@
(require 'ztree-diff-model)
(defconst ztree-diff-hidden-files-regexp "^\\."
- "Hidden files regexp. By default all filest starting with dot '.',
-including . and ..")
+ "Hidden files regexp.
+By default all filest starting with dot '.', including . and ..")
(defface ztreep-diff-header-face
'((((type tty pc) (class color)) :foreground "lightblue" :weight bold)
@@ -70,16 +70,16 @@ including . and ..")
(defvar ztree-diff-filter-list (list ztree-diff-hidden-files-regexp)
- "List of regexp file names to filter out. By default paths starting with
-dot (like .git) are ignored")
+ "List of regexp file names to filter out.
+By default paths starting with dot (like .git) are ignored")
(make-variable-buffer-local 'ztree-diff-filter-list)
(defvar ztree-diff-dirs-pair nil
- "Pair of the directories stored. Used to perform the full rescan")
+ "Pair of the directories stored. Used to perform the full rescan.")
(make-variable-buffer-local 'ztree-diff-dirs-pair)
(defvar ztree-diff-show-equal-files t
- "Show or not equal files/directories on both sides")
+ "Show or not equal files/directories on both sides.")
(make-variable-buffer-local 'ztree-diff-show-equal-files)
;;;###autoload
@@ -101,12 +101,14 @@ dot (like .git) are ignored")
(defun ztree-diff-node-face (node)
+ "Return the face for the NODE depending on diff status."
(let ((diff (ztree-diff-node-different node)))
(cond ((eq diff 'diff) ztreep-diff-model-diff-face)
((eq diff 'new) ztreep-diff-model-add-face)
- (t ztreep-diff-model-normal-face))))
+ (t ztreep-diff-model-normal-face))))
(defun ztree-diff-insert-buffer-header ()
+ "Insert the header to the ztree buffer."
(insert-with-face "Differences tree" ztreep-diff-header-face)
(newline-and-begin)
(when ztree-diff-dirs-pair
@@ -131,7 +133,7 @@ dot (like .git) are ignored")
(newline-and-begin))
(defun ztree-diff-full-rescan ()
- "Forces full rescan of the directory trees"
+ "Force full rescan of the directory trees."
(interactive)
(when (and ztree-diff-dirs-pair
(yes-or-no-p (format "Force full rescan?")))
@@ -140,6 +142,7 @@ dot (like .git) are ignored")
(defun ztree-diff-existing-common (node)
+ "Return the NODE if both left and right sides exist."
(let ((left (ztree-diff-node-left-path node))
(right (ztree-diff-node-right-path node)))
(if (and left right
@@ -149,12 +152,14 @@ dot (like .git) are ignored")
nil)))
(defun ztree-diff-existing-common-parent (node)
+ "Return the first node in up in hierarchy of the NODE which has both sides."
(let ((common (ztree-diff-existing-common node)))
(if common
common
(ztree-diff-existing-common-parent (ztree-diff-node-parent node)))))
(defun ztree-diff-do-partial-rescan (node)
+ "Partly rescan the NODE."
(let* ((common (ztree-diff-existing-common-parent node))
(parent (ztree-diff-node-parent common)))
(if (not parent)
@@ -167,7 +172,7 @@ dot (like .git) are ignored")
(defun ztree-diff-partial-rescan ()
- "Performs partial rescan on the current node"
+ "Perform partial rescan on the current node."
(interactive)
(let ((found (ztree-find-node-at-point)))
(when found
@@ -175,7 +180,8 @@ dot (like .git) are ignored")
(defun ztree-diff-simple-diff (node)
- "Create a simple diff buffer for files from left and right panels"
+ "Create a simple diff buffer for files from left and right panels.
+Argument NODE node containing paths to files to call a diff on."
(let* ((node-left (ztree-diff-node-left-path node))
(node-right (ztree-diff-node-right-path node)))
(when (and
@@ -189,7 +195,7 @@ dot (like .git) are ignored")
(defun ztree-diff-simple-diff-files ()
- "Create a simple diff buffer for files from left and right panels"
+ "Create a simple diff buffer for files from left and right panels."
(interactive)
(let ((found (ztree-find-node-at-point)))
(when found
@@ -197,10 +203,10 @@ dot (like .git) are ignored")
(ztree-diff-simple-diff node)))))
(defun ztree-diff-node-action (node hard)
- "Perform action on node:
+ "Perform action on NODE:
1 if both left and right sides present:
1.1 if they are differend
- 1.1.1 if hard ediff
+ 1.1.1 if HARD ediff
1.1.2 simple diff otherwiste
1.2 if they are the same - view left
2 if left or right present - view left or rigth"
@@ -222,6 +228,9 @@ dot (like .git) are ignored")
(defun ztree-diff-copy-file (node source-path destination-path copy-to-right)
+ "Update the NODE status and copy the file.
+File copied from SOURCE-PATH to DESTINATION-PATH.
+COPY-TO-RIGHT specifies which side of the NODE to update."
(let ((target-path (concat
(file-name-as-directory destination-path)
(file-name-nondirectory
@@ -248,6 +257,9 @@ dot (like .git) are ignored")
(defun ztree-diff-copy-dir (node source-path destination-path copy-to-right)
+ "Update the NODE status and copy the directory.
+Directory copied from SOURCE-PATH to DESTINATION-PATH.
+COPY-TO-RIGHT specifies which side of the NODE to update."
(let* ((src-path (file-name-as-directory source-path))
(target-path (file-name-as-directory destination-path))
(target-full-path (concat
@@ -276,6 +288,7 @@ dot (like .git) are ignored")
(defun ztree-diff-copy ()
+ "Copy the file under the cursor to other side."
(interactive)
(let ((found (ztree-find-node-at-point)))
(when found
@@ -321,7 +334,7 @@ dot (like .git) are ignored")
copy-to-right))))))))
(defun ztree-diff-view-file ()
- "View file at point, depending on side"
+ "View file at point, depending on side."
(interactive)
(let ((found (ztree-find-node-at-point)))
(when found
@@ -341,6 +354,7 @@ dot (like .git) are ignored")
(defun ztree-diff-delete-file ()
+ "Delete the file under the cursor."
(interactive)
(let ((found (ztree-find-node-at-point)))
(when found
@@ -365,19 +379,19 @@ dot (like .git) are ignored")
(when (yes-or-no-p (format "Delete the file [%s]%s ?"
(if delete-from-left "LEFT" "RIGHT")
remove-path))
- (let* ((delete-command
+ (let* ((delete-command
(if (file-directory-p remove-path)
'(delete-directory remove-path t)
'(delete-file remove-path t)))
(children (ztree-diff-node-children parent))
- (err
+ (err
(condition-case error-trap
(progn
(eval delete-command)
nil)
(error error-trap))))
(if err (message (concat "Error: " (nth 2 err)))
- (progn
+ (progn
(setq children (ztree-filter
#'(lambda (x) (not (ztree-diff-node-equal x
node)))
children))
@@ -388,25 +402,29 @@ dot (like .git) are ignored")
(defun ztree-node-is-in-filter-list (node)
- "Determine if the node is in filter list (and therefore
-apparently shall not be visible"
+ "Determine if the NODE is in filter list.
+If the node is in the filter list it shall not be visible"
(ztree-find ztree-diff-filter-list #'(lambda (rx) (string-match rx node))))
(defun ztree-node-is-visible (node)
+ "Determine if the NODE should be visible."
(and (ztree-diff-node-parent node) ; parent is always visible
(not (ztree-node-is-in-filter-list (ztree-diff-node-short-name node)))
(or ztree-diff-show-equal-files
(ztree-diff-node-different node))))
(defun ztree-diff-toggle-show-equal-files ()
+ "Toggle visibility of the equal files."
(interactive)
(setq ztree-diff-show-equal-files (not ztree-diff-show-equal-files))
(ztree-refresh-buffer))
;;;###autoload
(defun ztree-diff (dir1 dir2)
- "Creates an interactive buffer with the directory tree of the path given"
+ "Create an interactive buffer with the directory tree of the path given.
+Argument DIR1 left directory.
+Argument DIR2 right directory."
(interactive "DLeft directory \nDRight directory ")
(let* ((difference (ztree-diff-model-create dir1 dir2))
(buf-name (concat "*"
diff --git a/ztree-dir.el b/ztree-dir.el
index 64edaed..8cbd508 100644
--- a/ztree-dir.el
+++ b/ztree-dir.el
@@ -56,8 +56,8 @@
;;
(defconst ztree-hidden-files-regexp "^\\."
- "Hidden files regexp. By default all filest starting with dot '.',
-including . and ..")
+ "Hidden files regexp.
+By default all filest starting with dot '.', including . and ..")
;;
@@ -78,6 +78,7 @@ including . and ..")
;;
(defun ztree-insert-buffer-header ()
+ "Insert the header to the ztree buffer."
(let ((start (point)))
(insert "Directory tree")
(newline-and-begin)
@@ -86,11 +87,12 @@ including . and ..")
(newline-and-begin))
(defun ztree-file-not-hidden (filename)
+ "Determines if the file with FILENAME should be visible."
(not (string-match ztree-hidden-files-regexp
(file-short-name filename))))
(defun ztree-find-file (node hard)
- "Finds the file at NODE.
+ "Find the file at NODE.
If HARD is non-nil, the file is opened in another window.
Otherwise, the ztree window is used to find the file."
@@ -101,7 +103,7 @@ Otherwise, the ztree window is used to find the file."
;;;###autoload
(defun ztree-dir (path)
- "Creates an interactive buffer with the directory tree of the path given"
+ "Create an interactive buffer with the directory tree of the PATH given."
(interactive "DDirectory: ")
(when (and (file-exists-p path) (file-directory-p path))
(let ((buf-name (concat "*Directory " path " tree*")))
diff --git a/ztree-pkg.el b/ztree-pkg.el
index 4aa6e7f..2bbe9e0 100644
--- a/ztree-pkg.el
+++ b/ztree-pkg.el
@@ -1 +1,10 @@
+;;; ztree-pkg.el --- Package file for MELPA/ELPA
+
+;;; Commentary:
+;;
+
+;;; Code:
+
(define-package "ztree" "1.0.0" "Several text-tree applications")
+
+;;; ztree-pkg.el ends here
diff --git a/ztree-util.el b/ztree-util.el
index 6698d7d..5a9557e 100644
--- a/ztree-util.el
+++ b/ztree-util.el
@@ -28,7 +28,7 @@
;;; Code:
(defun ztree-find (where which)
- "find element of the list `where` matching predicate `which`"
+ "Find element of the list WHERE matching predicate WHICH."
(catch 'found
(dolist (elt where)
(when (funcall which elt)
@@ -36,34 +36,36 @@
nil))
(defun ztree-filter (condp lst)
- "Filter out elements of the list `lst` not satisfying predicate `condp`.
+ "Filter out elements not satisfying predicate CONDP in the list LST.
Taken from http://www.emacswiki.org/emacs/ElispCookbook#toc39";
(delq nil
(mapcar (lambda (x) (and (funcall condp x) x)) lst)))
(defun printable-string (string)
- "Strip newline character from file names, like 'Icon\n'"
- (replace-regexp-in-string "\n" "" string))
+ "Strip newline character from file names, like 'Icon\n.
+Argument STRING string to process.'."
+ (replace-regexp-in-string "\n" "" string))
(defun file-short-name (file)
- "Base file/directory name. Taken from
- http://lists.gnu.org/archive/html/emacs-devel/2011-01/msg01238.html";
+ "By given FILE name return base file/directory name.
+Taken from http://lists.gnu.org/archive/html/emacs-devel/2011-01/msg01238.html";
(printable-string (file-name-nondirectory (directory-file-name file))))
(defun newline-and-begin ()
+ "Move a point to the beginning of the next line."
(newline)
(beginning-of-line))
(defun car-atom (value)
- "Returns value if value is an atom, otherwise (car value) or nil.
-Used since car-safe returns nil for atoms"
+ "Return VALUE if value is an atom, otherwise (car value) or nil.
+Used since `car-safe' returns nil for atoms"
(if (atom value) value (car value)))
(defun insert-with-face (text face)
- "Insert text with the face provided"
+ "Insert TEXT with the FACE provided."
(let ((start (point)))
(insert text)
(put-text-property start (point) 'face face)))
@@ -73,8 +75,8 @@ Used since car-safe returns nil for atoms"
"Create a record (structure) and getters/setters.
Record is the following set of functions:
- - Record constructor with name \"record-name\"-create and list of
-arguments which will be assigned to record-fields
+ - Record constructor with name \"RECORD-NAME\"-create and list of
+arguments which will be assigned to RECORD-FIELDS
- Record getters with names \"record-name\"-\"field\" accepting one
argument - the record; \"field\" is from \"record-fields\" symbols
- Record setters with names \"record-name\"-set-\"field\" accepting two
@@ -97,7 +99,7 @@ will be expanded to the following functions:
;; with arguments list "record-fields" expanded
(defun ,ctor-name (,@record-fields)
(let ((,rec-var))
- ,@(mapcar #'(lambda (x)
+ ,@(mapcar #'(lambda (x)
(list 'setq rec-var (list 'plist-put rec-var (list
'quote x) x)))
record-fields)))
;; getters with names "record-name-field" where the "field"
diff --git a/ztree-view.el b/ztree-view.el
index f4893e1..642219f 100644
--- a/ztree-view.el
+++ b/ztree-view.el
@@ -61,23 +61,22 @@
(make-variable-buffer-local 'ztree-start-node)
(defvar ztree-line-to-node-table nil
- "List of tuples with full node(i.e. file/directory name
- and the line.")
+ "List of tuples with full node(i.e. file/directory name and the line.")
(make-variable-buffer-local 'ztree-line-to-node-table)
(defvar ztree-start-line nil
- "Index of the start line - the root")
+ "Index of the start line - the root.")
(make-variable-buffer-local 'ztree-start-line)
(defvar ztree-parent-lines-array nil
- "Array of parent lines, there the ith value of the array
-is the parent line for line i. If ith value is i - it is the root
-line")
+ "Array of parent lines.
+The ith value of the array is the parent line for line i.
+If ith value is i - it is the root line")
(make-variable-buffer-local 'ztree-parent-lines-array)
(defvar ztree-count-subsequent-bs nil
- "Counter for the subsequest BS keys (to identify double BS). Used
-in order to not to use cl package and lexical-let")
+ "Counter for the subsequest BS keys (to identify double BS).
+Used in order to not to use cl package and `lexical-let'")
(make-variable-buffer-local 'ztree-count-subsequent-bs)
(defvar ztree-line-tree-properties nil
@@ -92,21 +91,20 @@ MUST inster newline at the end!")
(make-variable-buffer-local 'ztree-tree-header-fun)
(defvar ztree-node-short-name-fun nil
- "Function which creates a pretty-printable short string from
-the node")
+ "Function which creates a pretty-printable short string from the node.")
(make-variable-buffer-local 'ztree-node-short-name-fun)
(defvar ztree-node-is-expandable-fun nil
- "Function which determines if the node is expandable,
-for example if the node is a directory")
+ "Function which determines if the node is expandable.
+For example if the node is a directory")
(make-variable-buffer-local 'ztree-node-is-expandable-fun)
(defvar ztree-node-equal-fun nil
- "Function which determines if the 2 nodes are equal")
+ "Function which determines if the 2 nodes are equal.")
(make-variable-buffer-local 'ztree-node-equal-fun)
(defvar ztree-node-contents-fun nil
- "Function returning list of node contents")
+ "Function returning list of node contents.")
(make-variable-buffer-local 'ztree-node-contents-fun)
(defvar ztree-node-side-fun nil
@@ -116,15 +114,15 @@ the buffer is split to 2 trees")
(make-variable-buffer-local 'ztree-node-side-fun)
(defvar ztree-node-face-fun nil
- "Function returning face for the node")
+ "Function returning face for the node.")
(make-variable-buffer-local 'ztree-node-face-fun)
(defvar ztree-node-action-fun nil
- "Function called when Enter/Space pressed on the node")
+ "Function called when Enter/Space pressed on the node.")
(make-variable-buffer-local 'ztree-node-action-fun)
(defvar ztree-node-showp-fun nil
- "Function called to decide if the node should be visible")
+ "Function called to decide if the node should be visible.")
(make-variable-buffer-local 'ztree-node-showp-fun)
@@ -193,13 +191,14 @@ the buffer is split to 2 trees")
(defun ztree-find-node-in-line (line)
- "Search through the array of node-line pairs and return the
-node for the line specified"
+ "Return the node for the LINE specified.
+Search through the array of node-line pairs."
(gethash line ztree-line-to-node-table))
(defun ztree-find-node-at-point ()
- "Returns cons pair (node, side) for the current point or nil
-if there is no node"
+ "Find the node at point.
+Returns cons pair (node, side) for the current point
+or nil if there is no node"
(let ((center (/ (window-width) 2))
(node (ztree-find-node-in-line (line-number-at-pos))))
(when node
@@ -207,26 +206,31 @@ if there is no node"
(defun ztree-is-expanded-node (node)
- "Find if the node is in the list of expanded nodes"
+ "Find if the NODE is in the list of expanded nodes."
(ztree-find ztree-expanded-nodes-list
#'(lambda (x) (funcall ztree-node-equal-fun x node))))
(defun ztree-set-parent-for-line (line parent)
+ "For given LINE set the PARENT in the global array."
(aset ztree-parent-lines-array (- line ztree-start-line) parent))
(defun ztree-get-parent-for-line (line)
+ "For given LINE return a parent."
(when (and (>= line ztree-start-line)
(< line (+ (length ztree-parent-lines-array) ztree-start-line)))
(aref ztree-parent-lines-array (- line ztree-start-line))))
(defun scroll-to-line (line)
- "Recommended way to set the cursor to specified line"
+ "Recommended way to set the cursor to specified LINE."
(goto-char (point-min))
(forward-line (1- line)))
(defun ztree-do-toggle-expand-subtree-iter (node state)
+ "Iteration in expanding subtree.
+Argument NODE current node.
+Argument STATE node state."
(when (funcall ztree-node-is-expandable-fun node)
(let ((children (funcall ztree-node-contents-fun node)))
(ztree-do-toggle-expand-state node state)
@@ -235,13 +239,14 @@ if there is no node"
(defun ztree-do-toggle-expand-subtree ()
+ "Implements the subtree expand."
(let* ((line (line-number-at-pos))
(node (ztree-find-node-in-line line))
;; save the current window start position
(current-pos (window-start)))
;; only for expandable nodes
(when (funcall ztree-node-is-expandable-fun node)
- ;; get the current expand state and invert it
+ ;; get the current expand state and invert it
(let ((do-expand (not (ztree-is-expanded-node node))))
(ztree-do-toggle-expand-subtree-iter node do-expand))
;; refresh buffer and scroll back to the saved line
@@ -251,6 +256,9 @@ if there is no node"
(defun ztree-do-perform-action (hard)
+ "Toggle expand/collapsed state for nodes or perform an action.
+HARD specifies (t or nil) if the hard action, binded on RET,
+should be performed on node."
(let* ((line (line-number-at-pos))
(node (ztree-find-node-in-line line)))
(when node
@@ -265,18 +273,18 @@ if there is no node"
;; refresh buffer and scroll back to the saved line
(ztree-refresh-buffer line)
;; restore window start position
- (set-window-start (selected-window) current-pos)))))
+ (set-window-start (selected-window) current-pos)))))
(defun ztree-perform-action ()
- "Toggle expand/collapsed state for nodes or perform hard action,
-binded on RET, on node"
+ "Toggle expand/collapsed state for nodes or perform the action.
+Performs the hard action, binded on RET, on node."
(interactive)
(ztree-do-perform-action t))
(defun ztree-perform-soft-action ()
- "Toggle expand/collapsed state for nodes or perform soft action,
-binded on Space, on node"
+ "Toggle expand/collapsed state for nodes or perform the action.
+Performs the soft action, binded on Space, on node."
(interactive)
(ztree-do-perform-action nil))
@@ -287,7 +295,7 @@ binded on Space, on node"
(ztree-do-toggle-expand-subtree))
(defun ztree-do-toggle-expand-state (node do-expand)
- "Set the expanded state of the node to do-expand"
+ "Set the expanded state of the NODE to DO-EXPAND."
(if (not do-expand)
(setq ztree-expanded-nodes-list
(ztree-filter
@@ -297,13 +305,14 @@ binded on Space, on node"
(defun ztree-toggle-expand-state (node)
- "Toggle expanded/collapsed state for nodes"
+ "Toggle expanded/collapsed state for NODE."
(ztree-do-toggle-expand-state node (not (ztree-is-expanded-node node))))
(defun ztree-move-up-in-tree ()
- "Action on Backspace key: to jump to the line of a parent node or
-if previous key was Backspace - close the node"
+ "Action on Backspace key.
+Jump to the line of a parent node. If previous key was Backspace
+then close the node."
(interactive)
(when ztree-parent-lines-array
(let* ((line (line-number-at-pos (point)))
@@ -321,8 +330,8 @@ if previous key was Backspace - close the node"
(defun ztree-get-splitted-node-contens (node)
- "Returns pair of 2 elements: list of expandable nodes and
-list of leafs"
+ "Return pair of 2 elements: list of expandable nodes and list of leafs.
+Argument NODE node which contents will be returned."
(let ((nodes (funcall ztree-node-contents-fun node))
(comp #'(lambda (x y)
(string< (funcall ztree-node-short-name-fun x)
@@ -336,7 +345,8 @@ list of leafs"
(defun ztree-draw-char (c x y &optional face)
- "Draw char c at the position (1-based) (x y)"
+ "Draw char C at the position (1-based) (X Y).
+Optional argument FACE face to use to draw a character."
(save-excursion
(scroll-to-line y)
(beginning-of-line)
@@ -346,8 +356,9 @@ list of leafs"
(put-text-property (1- (point)) (point) 'face (if face face
'ztreep-arrow-face))))
(defun ztree-draw-vertical-line (y1 y2 x &optional face)
- "Draw a vertical line of '|' characters"
- (let ((count (abs (- y1 y2))))
+ "Draw a vertical line of '|' characters from Y1 row to Y2 in X column.
+Optional argument FACE face to draw line with."
+ (let ((count (abs (- y1 y2))))
(if (> y1 y2)
(progn
(dotimes (y count)
@@ -356,11 +367,13 @@ list of leafs"
(progn
(dotimes (y count)
(ztree-draw-char ?\| x (+ y1 y) face))
- (ztree-draw-char ?\| x (+ y1 count) face)))))
+ (ztree-draw-char ?\| x (+ y1 count) face)))))
(defun ztree-draw-vertical-rounded-line (y1 y2 x &optional face)
- "Draw a vertical line of '|' characters finishing with '`' character"
- (let ((count (abs (- y1 y2))))
+ "Draw a vertical line of '|' characters finishing with '`' character.
+Draws the line from Y1 row to Y2 in X column.
+Optional argument FACE facet to draw the line with."
+ (let ((count (abs (- y1 y2))))
(if (> y1 y2)
(progn
(dotimes (y count)
@@ -369,10 +382,11 @@ list of leafs"
(progn
(dotimes (y count)
(ztree-draw-char ?\| x (+ y1 y) face))
- (ztree-draw-char ?\` x (+ y1 count) face)))))
+ (ztree-draw-char ?\` x (+ y1 count) face)))))
(defun ztree-draw-horizontal-line (x1 x2 y)
+ "Draw the horizontal line from column X1 to X2 in the row Y."
(if (> x1 x2)
(dotimes (x (1+ (- x1 x2)))
(ztree-draw-char ?\- (+ x2 x) y))
@@ -381,7 +395,9 @@ list of leafs"
(defun ztree-draw-tree (tree depth start-offset)
- "Draw the tree of lines with parents"
+ "Draw the TREE of lines with parents.
+Argument DEPTH current depth.
+Argument START-OFFSET column to start drawing from."
(if (atom tree)
nil
(let* ((root (car tree))
@@ -424,7 +440,8 @@ list of leafs"
(car-atom child)))))))))
(defun ztree-fill-parent-array (tree)
- ;; set the root line
+ "Set the root lines array.
+Argument TREE nodes tree to create an array of lines from."
(let ((root (car tree))
(children (cdr tree)))
(dolist (child children)
@@ -434,16 +451,17 @@ list of leafs"
(defun ztree-insert-node-contents (path)
- ;; insert node contents with initial depth 0
- ;; ztree-insert-node-contents-1 return the tree of line
- ;; numbers to determine who is parent line of the
- ;; particular line. This tree is used to draw the
- ;; graph
+ "Insert node contents with initial depth 0.
+`ztree-insert-node-contents-1' return the tree of line
+numbers to determine who is parent line of the
+particular line. This tree is used to draw the
+graph.
+Argument PATH start node."
(let ((tree (ztree-insert-node-contents-1 path 0))
;; number of 'rows' in tree is last line minus start line
(num-of-items (- (line-number-at-pos (point)) ztree-start-line)))
;; create a parents array to store parents of lines
- ;; parents array used for navigation with the BS
+ ;; parents array used for navigation with the BS
(setq ztree-parent-lines-array (make-vector num-of-items 0))
;; set the root node in lines parents array
(ztree-set-parent-for-line ztree-start-line ztree-start-line)
@@ -464,6 +482,7 @@ list of leafs"
(defun ztree-insert-node-contents-1 (node depth)
+ "Recursively insert contents of the NODE with current DEPTH."
(let* ((expanded (ztree-is-expanded-node node))
;; insert node entry with defined depth
(root-line (ztree-insert-entry node depth expanded))
@@ -476,7 +495,7 @@ list of leafs"
(nodes (car contents)) ; expandable entries - nodes
(leafs (cdr contents))) ; leafs - which doesn't have subleafs
;; iterate through all expandable entries to insert them first
- (dolist (node nodes)
+ (dolist (node nodes)
;; if it is not in the filter list
(when (funcall ztree-node-showp-fun node)
;; insert node on the next depth level
@@ -492,10 +511,11 @@ list of leafs"
(push (ztree-insert-entry leaf (1+ depth) nil)
children)))))
;; result value is the list - head is the root line,
- ;; rest are children
+ ;; rest are children
(cons root-line children)))
(defun ztree-insert-entry (node depth expanded)
+ "Inselt the NODE to the current line with specified DEPTH and EXPANDED
state."
(let ((line (line-number-at-pos))
(expandable (funcall ztree-node-is-expandable-fun node))
(short-name (funcall ztree-node-short-name-fun node)))
@@ -515,7 +535,7 @@ list of leafs"
(funcall ztree-node-face-fun node)))
(puthash line side ztree-line-tree-properties))
(ztree-insert-single-entry short-name depth expandable expanded 0))
- (puthash line node ztree-line-to-node-table)
+ (puthash line node ztree-line-to-node-table)
(newline-and-begin)
line))
@@ -523,7 +543,11 @@ list of leafs"
expandable expanded
offset
&optional face)
- (let ((node-sign #'(lambda (exp)
+ "Writes a SHORT-NAME in a proper position with the type given.
+Writes a string with given DEPTH, prefixed with [ ] if EXPANDABLE
+and [-] or [+] depending on if it is EXPANDED from the specified OFFSET.
+Optional argument FACE face to write text with."
+ (let ((node-sign #'(lambda (exp)
(insert "[" (if exp "-" "+") "]")
(set-text-properties (- (point) 3)
(point)
@@ -536,7 +560,7 @@ list of leafs"
(insert-char ?\s 3))) ; insert 3 spaces
(when (> (length short-name) 0)
(if expandable
- (progn
+ (progn
(funcall node-sign expanded) ; for expandable nodes insert
"[+/-]"
(insert " ")
(put-text-property 0 (length short-name)
@@ -549,18 +573,21 @@ list of leafs"
(insert short-name))))))
(defun ztree-jump-side ()
+ "Jump to another side for 2-sided trees."
(interactive)
(when ztree-node-side-fun ; 2-sided tree
(let ((center (/ (window-width) 2)))
- (cond ((< (current-column) center)
+ (cond ((< (current-column) center)
(move-to-column (1+ center)))
- ((> (current-column) center)
+ ((> (current-column) center)
(move-to-column 1))
(t nil)))))
(defun ztree-refresh-buffer (&optional line)
+ "Refresh the buffer.
+Optional argument LINE scroll to the line given."
(interactive)
(when (and (equal major-mode 'ztree-mode)
(boundp 'ztree-start-node))
@@ -591,6 +618,20 @@ list of leafs"
action-fun
&optional node-side-fun
)
+ "Create a ztree view buffer configured with parameters given.
+Argument BUFFER-NAME Name of the buffer created.
+Argument START-NODE Starting node - the root of the tree.
+Argument FILTER-FUN Function which will define if the node should not be
+visible.
+Argument HEADER-FUN Function which inserts the header into the buffer
+before drawing the tree.
+Argument SHORT-NAME-FUN Function which return the short name for a node given.
+Argument EXPANDABLE-P Function to determine if the node is expandable.
+Argument EQUAL-FUN An equality function for nodes.
+Argument CHILDREN-FUN Function to get children from the node.
+Argument FACE-FUN Function to determine face of the node.
+Argument ACTION-FUN an action to perform when the Return is pressed.
+Optional argument NODE-SIDE-FUN Determines the side of the node."
(let ((buf (get-buffer-create buffer-name)))
(switch-to-buffer buf)
(ztree-mode)
