[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] scratch/add-vdiff 7d60015 201/258: Add some doctrings
From: |
Justin Burkett |
Subject: |
[elpa] scratch/add-vdiff 7d60015 201/258: Add some doctrings |
Date: |
Wed, 17 May 2017 08:13:50 -0400 (EDT) |
branch: scratch/add-vdiff
commit 7d6001578707abf5604fac0e72faae313fcf0201
Author: justbur <address@hidden>
Commit: justbur <address@hidden>
Add some doctrings
---
vdiff.el | 24 ++++++++++++++++++++++--
1 file changed, 22 insertions(+), 2 deletions(-)
diff --git a/vdiff.el b/vdiff.el
index eee7394..f2b57f1 100644
--- a/vdiff.el
+++ b/vdiff.el
@@ -211,8 +211,10 @@ because those are handled differently.")
("Ignore blank lines (-B)" . "-B")))
;; Sessions
-(defvar vdiff--temp-session nil)
-(defvar-local vdiff--session nil)
+(defvar vdiff--temp-session nil
+ "Temporarily stores new vdiff session globally.")
+(defvar-local vdiff--session nil
+ "Holds reference to local vdiff session in each vdiff buffer.")
(cl-defstruct vdiff-session
;; buffers
buffers
@@ -237,12 +239,14 @@ because those are handled differently.")
;; * Utilities
(defun vdiff--maybe-int (str)
+ "Return an int>=0 from STR."
(let ((num (and str (string-to-number str))))
(when (and (numberp num)
(>= num 0))
num)))
(defun vdiff--non-nil-list (&rest args)
+ "Make ARGS into list and remove nils."
(delq nil (apply #'list args)))
(defun vdiff--buffer-a-p ()
@@ -267,6 +271,7 @@ because those are handled differently.")
(current-buffer)))
(defun vdiff--buffer-p ()
+ "Non-nil if in any vdiff buffer"
(cond ((vdiff--buffer-a-p) 'a)
((vdiff--buffer-b-p) 'b)
((vdiff--buffer-c-p) 'c)))
@@ -313,6 +318,8 @@ because those are handled differently.")
(length (vdiff--overlay-marker ovr)))))
(defun vdiff--read-3way-target (ovr &optional just-one)
+ "Read a target overlay when sending or receiving a hunk from
+one buffer to another. Only applies in 3-way diffs."
(when vdiff-3way-mode
(let* ((all-ovrs (vdiff--all-overlays ovr))
(other-ovrs (remq ovr all-ovrs))
@@ -358,6 +365,8 @@ because those are handled differently.")
(forward-line (1- n)))
(defun vdiff--overlay-at-pos (&optional pos)
+ "Return first vdiff overlay found at POS which defaults to
+point."
(let ((pos (or pos (point))))
(catch 'yes
(dolist (ovr (overlays-at pos))
@@ -365,18 +374,21 @@ because those are handled differently.")
(throw 'yes ovr))))))
(defun vdiff--hunk-at-point-p ()
+ "Return first vdiff hunk overlay found at point."
(let ((ovr (vdiff--overlay-at-pos)))
(and (overlayp ovr)
(overlay-get ovr 'vdiff-type)
(not (eq (overlay-get ovr 'vdiff-type) 'fold)))))
(defun vdiff--fold-at-point-p ()
+ "Return first vdiff fold overlay found at point."
(let ((ovr (vdiff--overlay-at-pos)))
(and (overlayp ovr)
(overlay-get ovr 'vdiff-type)
(eq (overlay-get ovr 'vdiff-type) 'fold))))
(defun vdiff--overlays-in-region (beg end)
+ "Return any vdiff overlays found within BEG and END."
(let (ovrs)
(dolist (ovr (overlays-in beg end))
(when (overlay-get ovr 'vdiff-type)
@@ -384,6 +396,8 @@ because those are handled differently.")
(nreverse ovrs)))
(defun vdiff--maybe-exit-overlay (&optional up no-fold)
+ "Move point out of any vdiff overlays. Move down unless UP is
+non-nil. Ignore folds if NO-FOLD is non-nil."
(let* ((ovr (vdiff--overlay-at-pos))
(type (when ovr (overlay-get ovr 'vdiff-type))))
(when (and type
@@ -481,6 +495,8 @@ because those are handled differently.")
(set-process-sentinel proc #'vdiff--diff-refresh-1))))
(defun vdiff--encode-range (insert beg &optional end)
+ "Normalize BEG and END of range. INSERT indicates that this is
+an addition when compared to other vdiff buffers."
(let* ((beg (vdiff--maybe-int beg))
(end (vdiff--maybe-int end)))
(cond ((and end insert)
@@ -491,6 +507,7 @@ because those are handled differently.")
(cons beg (or end beg))))))
(defun vdiff--parse-diff (buf)
+ "Parse diff output in BUF and return list of hunks."
(let (res)
(with-current-buffer buf
(goto-char (point-min))
@@ -515,6 +532,7 @@ because those are handled differently.")
(nreverse res)))
(defun vdiff--parse-diff3 (buf)
+ "Parse diff3 output in BUF and return list of hunks."
(catch 'final-res
(let (res)
(with-current-buffer buf
@@ -726,6 +744,7 @@ SYNTAX-CODE."
(vdiff-refine-this-hunk "w" ovr))
(defun vdiff-remove-refinements-in-hunk (ovr)
+ "Remove any refinement overlays in the hunk overlay OVR."
(interactive (list (vdiff--overlay-at-pos)))
(dolist (chg-ovr (vdiff--all-overlays ovr))
(with-current-buffer (overlay-buffer chg-ovr)
@@ -804,6 +823,7 @@ of a \"word\"."
;; * Add overlays
(defun vdiff--make-subtraction-string (n-lines)
+ "Make string to fill in space for lines missing in a buffer."
(let* ((width (1- (window-text-width (get-buffer-window (current-buffer)))))
(win-height (window-height (get-buffer-window (current-buffer))))
(max-lines (floor (* 0.7 win-height)))
- [elpa] scratch/add-vdiff 667a7e4 144/258: Generalize data structures to prepare for diff3, (continued)
- [elpa] scratch/add-vdiff 667a7e4 144/258: Generalize data structures to prepare for diff3, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 059d288 208/258: Update gitignore, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff cfad650 207/258: Provide missing function for emacs-nox users, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff e567468 221/258: vdiff-magit: Port show-working-tree, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 30b0f9c 213/258: Add vdiff-magit.el with two functions, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 64430c3 215/258: Cleanup merge, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 19f4616 217/258: vdiff-magit: Port compare and show-commit, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff a81d62a 240/258: README: Update recent changes, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 9be4fe3 066/258: Update install instructions in README, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff eda4b1b 204/258: Force update of window-start in manual calls to scroll func, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 7d60015 201/258: Add some doctrings,
Justin Burkett <=
- [elpa] scratch/add-vdiff 3037be6 222/258: vdiff-magit: Cleanup references in dwim, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 615e7bd 228/258: vdiff-magit: Fix killing of buffers in stage, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff a040a4b 246/258: vdiff: Add vdiff-merge-conflict, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 7fbb20e 205/258: Nil temp-session after using it, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 048d544 198/258: Pass session explicitly from refresh sentinel, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff ed25084 224/258: vdiff-magit: Fix some strings, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 432534d 230/258: vdiff-magit: Don't use vdiff-magit-resolve yet, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff 1d79425 235/258: vdiff-magit: Cleanup header, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff c2c991d 209/258: Add initial vdiff-magit work, Justin Burkett, 2017/05/17
- [elpa] scratch/add-vdiff fb3097c 247/258: vdiff: Check if window exists before forcing vscroll, Justin Burkett, 2017/05/17