[PATCH 0/2] Documentation
Rémi Vanicat
I send Two patch with no new code:
the first fix style error in comment, docstring and error message
the second add docstring to a bunch of magit's function (the one
referring to sectioning.
Do not hesitate to use checkdoc-minor-mode in future modification to
follow more easily Emacs recommended style for documentation and
messages.
--
Rémi Vanicat
Rémi Vanicat
checkdoc-minor-mode and Aspell.
Some indent and minor code style fix too
---
magit.el | 162 ++++++++++++++++++++++++++++++++------------------------------
1 files changed, 83 insertions(+), 79 deletions(-)
diff --git a/magit.el b/magit.el
index 56c57a2..7632448 100644
--- a/magit.el
+++ b/magit.el
@@ -20,7 +20,7 @@
;; You should have received a copy of the GNU General Public License
;; along with Magit. If not, see <http://www.gnu.org/licenses/>.
-;;; Commentary
+;;; Commentary:
;; Invoking the magit-status function will show a buffer with the
;; status of the current git repository and its working tree. That
@@ -61,6 +61,7 @@
(require 'easymenu)
(require 'diff-mode)
+;;; Code:
(defgroup magit nil
"Controlling Git from Emacs."
:prefix "magit-"
@@ -78,12 +79,12 @@
(defcustom magit-repo-dirs nil
"Directories containing Git repositories.
-Magit will look into these directories for Git repositories and offers them as choices for magit-status."
+Magit will look into these directories for Git repositories and offers them as choices for `magit-status'."
:group 'magit
:type '(repeat string))
(defcustom magit-repo-dirs-depth 3
- "When looking for Git repositors below the directories in magit-repo-dirs, Magit will only descend this many levels deep."
+ "When looking for Git repository below the directories in `magit-repo-dirs', Magit will only descend this many levels deep."
:group 'magit
:type 'integer)
@@ -106,12 +107,12 @@ Setting this to nil will make it do nothing, setting it to t will arrange things
(const :tag "Ask to stage everything" ask-stage)))
(defcustom magit-commit-signoff nil
- "When performing git commit adds --signoff"
+ "When performing git commit adds --signoff."
:group 'magit
:type 'boolean)
(defcustom magit-log-cutoff-length 100
- "The maximum number of commits to show in the log and whazzup buffers"
+ "The maximum number of commits to show in the log and whazzup buffers."
:group 'magit
:type 'integer)
@@ -123,7 +124,7 @@ Setting this to nil will make it do nothing, setting it to t will arrange things
(integer :tag "After this many seconds")))
(defcustom magit-log-edit-confirm-cancellation nil
- "Require acknowledgement before cancelling the log edit buffer."
+ "Require acknowledgment before canceling the log edit buffer."
:group 'magit
:type 'boolean)
@@ -248,8 +249,7 @@ Many Magit faces inherit from this one by default."
"Function to be called when requesting input from the user.")
(defvar magit-omit-untracked-dir-contents nil
- "When non-nil magit will only list an untracked directory, not
- its contents.")
+ "When non-nil magit will only list an untracked directory, not its contents.")
(defface magit-log-head-label-local
'((((class color) (background light))
@@ -277,7 +277,7 @@ Many Magit faces inherit from this one by default."
(and transient-mark-mode mark-active)))
(defun magit-goto-line (line)
- ;; Like goto-line but doesn't set the mark.
+ "Like `goto-line' but doesn't set the mark."
(save-restriction
(widen)
(goto-char 1)
@@ -313,7 +313,7 @@ Many Magit faces inherit from this one by default."
(defun magit-git-string (&rest args)
(magit-trim-line (magit-git-output args)))
-(defun magit-git-lines (&rest args)
+(defun magit-git-lines (&rest args)
(magit-split-lines (magit-git-output args)))
(defun magit-git-exit-code (&rest args)
@@ -365,7 +365,7 @@ Many Magit faces inherit from this one by default."
(push (cons key (car value)) result)
(let ((sub (magit-remove-conflicts
(mapcar (lambda (entry)
- (let ((dir (directory-file-name
+ (let ((dir (directory-file-name
(subseq entry 0 (- (length key))))))
(cons (concat (file-name-nondirectory dir) "/" key)
entry)))
@@ -481,7 +481,7 @@ Many Magit faces inherit from this one by default."
(defun magit-choose-parent-id (commit op)
(let* ((parents (magit-commit-parents commit)))
(if (> (length parents) 1)
- (error "Can't %s merge commits." op)
+ (error "Can't %s merge commits" op)
nil)))
;;; Revisions and ranges
@@ -596,9 +596,8 @@ Many Magit faces inherit from this one by default."
(magit-find-section (magit-section-path s)
magit-old-top-section))))
(if magit-top-section
- (setf (magit-section-children magit-top-section)
- (cons s (magit-section-children magit-top-section)))
- (setq magit-top-section s))
+ (push s (magit-section-children magit-top-section))
+ (setq magit-top-section s))
(if old
(setf (magit-section-hidden s) (magit-section-hidden old)))
s))
@@ -610,7 +609,7 @@ Many Magit faces inherit from this one by default."
(if parent
(setf (magit-section-children parent)
(delq section (magit-section-children parent)))
- (setq magit-top-section nil))))
+ (setq magit-top-section nil))))
(defmacro magit-with-section (title type &rest body)
(declare (indent 2))
@@ -859,13 +858,14 @@ Many Magit faces inherit from this one by default."
(defun magit-section-hideshow (flag-or-func)
(let ((section (magit-current-section)))
- (cond ((magit-section-parent section)
- (goto-char (magit-section-beginning section))
- (if (functionp flag-or-func)
- (funcall flag-or-func section)
- (magit-section-set-hidden section flag-or-func))))))
+ (when (magit-section-parent section)
+ (goto-char (magit-section-beginning section))
+ (if (functionp flag-or-func)
+ (funcall flag-or-func section)
+ (magit-section-set-hidden section flag-or-func)))))
(defun magit-show-section ()
+ "Show current section."
(interactive)
(magit-section-hideshow nil))
@@ -922,8 +922,8 @@ Many Magit faces inherit from this one by default."
(when (< level threshold)
(if path
(magit-section-show-level (car path) (1+ level) threshold (cdr path))
- (dolist (c (magit-section-children section))
- (magit-section-show-level c (1+ level) threshold nil)))))
+ (dolist (c (magit-section-children section))
+ (magit-section-show-level c (1+ level) threshold nil)))))
(defun magit-show-level (level all)
(magit-with-refresh
@@ -1028,9 +1028,9 @@ Many Magit faces inherit from this one by default."
clauses)
,@(if opname
`(((not ,type)
- (error "Nothing to %s here." ,opname))
+ (error "Nothing to %s here" ,opname))
(t
- (error "Can't %s a %s."
+ (error "Can't %s a %s"
,opname
(or (get ,type 'magit-description)
,type)))))))))
@@ -1069,7 +1069,7 @@ Many Magit faces inherit from this one by default."
&optional logline noerase noerror nowait input)
(if (and magit-process
(get-buffer "*magit-process*"))
- (error "Git is already running."))
+ (error "Git is already running"))
(let ((cmd (car cmd-and-args))
(args (cdr cmd-and-args))
(dir default-directory)
@@ -1143,7 +1143,7 @@ Many Magit faces inherit from this one by default."
(magit-need-refresh magit-process-client-buffer))))
(or successp
noerror
- (error "Git failed."))
+ (error "Git failed"))
successp)))
(defun magit-process-sentinel (process event)
@@ -1408,15 +1408,16 @@ Many Magit faces inherit from this one by default."
pos)
(defun magit-correct-point-after-command ()
- ;; Emacs often leaves point in invisible regions, it seems. To fix
- ;; this, we move point ourselves and never let Emacs do its own
- ;; adjustements.
- ;;
- ;; When point has to be moved out of an invisible region, it can be
- ;; moved to its end or its beginning. We usually move it to its
- ;; end, except when that would move point back to where it was
- ;; before the last command.
- ;;
+ "Move point outside of invisible regions.
+
+Emacs often leaves point in invisible regions, it seems. To fix
+this, we move point ourselves and never let Emacs do its own
+adjustments.
+
+When point has to be moved out of an invisible region, it can be
+moved to its end or its beginning. We usually move it to its
+end, except when that would move point back to where it was
+before the last command."
(if (invisible-p (point))
(let ((end (magit-invisible-region-end (point))))
(goto-char (if (= end last-point)
@@ -1792,7 +1793,7 @@ Please see the manual for a complete description of Magit.
(defun magit-hunk-item-diff (hunk)
(let ((diff (magit-section-parent hunk)))
(or (eq (magit-section-type diff) 'diff)
- (error "Huh? Parent of hunk not a diff."))
+ (error "Huh? Parent of hunk not a diff"))
diff))
(defun magit-diff-item-insert-header (diff buf)
@@ -1849,10 +1850,10 @@ Please see the manual for a complete description of Magit.
(beginning-of-line)
(let ((line (line-number-at-pos)))
(if (looking-at "-")
- (error "Can't visit removed lines."))
+ (error "Can't visit removed lines"))
(goto-char (magit-section-beginning hunk))
(if (not (looking-at "@@+ .* \\+\\([0-9]+\\),[0-9]+ @@+"))
- (error "Hunk header not found."))
+ (error "Hunk header not found"))
(let ((target (parse-integer (match-string 1))))
(forward-line)
(while (< (line-number-at-pos) line)
@@ -1918,13 +1919,13 @@ Please see the manual for a complete description of Magit.
"\\(?:\\((.+?)\\) \\)?" ; refs (3)
"\\(.*\\)" ; msg (4)
"\\)?$")
- "Regexp used to extract elements of git log output with
---pretty=oneline with graph, or --pretty=format:* %H %s")
+ "Regexp used to extract elements of git log output.
+Those output are generated by --pretty=oneline with graph, or --pretty=format:* %H %s")
(defvar magit-present-log-line-function 'magit-present-log-line
- "The function to use when generating a log line. It takes four
-args: CHART, SHA1, REFS and MESSAGE. The function must return a
-string which will represent the log line.")
+ "The function to use when generating a log line.
+It takes four args: CHART, SHA1, REFS and MESSAGE. The function
+must return a string which will represent the log line.")
(defun magit-present-log-line (graph sha1 refs message)
"The default log line generator."
@@ -2141,7 +2142,7 @@ string which will represent the log line.")
(magit-insert-unpushed-svn-commits t))))))
(defun magit-init (dir)
- "Initialize git repository in specified directory"
+ "Initialize git repository in the DIR directory."
(interactive (list (read-directory-name "Directory for Git repository: ")))
(let ((topdir (magit-get-top-dir dir)))
(when (or (not topdir)
@@ -2152,7 +2153,7 @@ string which will represent the log line.")
"There is a Git repository in %s. Create another in %s? ")
topdir dir)))
(unless (file-directory-p dir)
- (and (y-or-n-p (format "Directory %s does not exists. Create it? " dir))
+ (and (y-or-n-p (format "Directory %s does not exists. Create it? " dir))
(make-directory dir)))
(let ((default-directory dir))
(magit-run* (list "git" "init"))))))
@@ -2167,7 +2168,7 @@ string which will represent the log line.")
(save-some-buffers (eq magit-save-some-buffers 'dontask)))
(let ((topdir (magit-get-top-dir dir)))
(unless topdir
- (when (y-or-n-p (format "There is no Git repository in %S. Create one? "
+ (when (y-or-n-p (format "There is no Git repository in %S. Create one? "
dir))
(magit-init dir)
(setq topdir (magit-get-top-dir dir))))
@@ -2214,7 +2215,7 @@ string which will represent the log line.")
(magit-apply-hunk-item-reverse item "--cached"))
((staged diff)
(if (eq (car info) 'unmerged)
- (error "Can't unstage a unmerged file. Resolve it first."))
+ (error "Can't unstage a unmerged file. Resolve it first"))
(magit-run-git "reset" "-q" "HEAD" "--" (magit-diff-item-file item)))
((unstaged *)
(error "Already unstaged"))
@@ -2274,8 +2275,8 @@ string which will represent the log line.")
(magit-section-info sec))))
(defun magit-manual-merge (rev)
- "Merge (without commiting) REV. Given a prefix-arg then the
-merge will be squashed."
+ "Merge (without committing) REV.
+Given a prefix-arg then the merge will be squashed."
(interactive
(list (magit-read-rev (concat "Manually merge"
(when current-prefix-arg
@@ -2383,15 +2384,16 @@ merge will be squashed."
result))
(defvar magit-get-svn-ref-info-cache nil
- "As `magit-get-svn-ref-info' might be considered a quite
- expensive operation a cache is taken so that `magit-status'
- doesn't repeatedly call it.")
+ "A cache for svn-ref-info.
+As `magit-get-svn-ref-info' might be considered a quite
+expensive operation a cache is taken so that `magit-status'
+doesn't repeatedly call it.")
(defun magit-get-svn-ref-info (&optional use-cache)
- "Gather details about the current git-svn repository (nil if
-there isn't one). Keys of the alist are ref-path, trunk-ref-name
-and local-ref-name. If USE-CACHE is non-nil then return the value
-of `magit-get-svn-ref-info-cache'."
+ "Gather details about the current git-svn repository.
+Return nil if there isn't one. Keys of the alist are ref-path,
+trunk-ref-name and local-ref-name.
+If USE-CACHE is non-nil then return the value of `magit-get-svn-ref-info-cache'."
(if use-cache
magit-get-svn-ref-info-cache
(let* ((fetch (magit-get "svn-remote" "svn" "fetch"))
@@ -2423,8 +2425,8 @@ of `magit-get-svn-ref-info-cache'."
(cons 'url url))))))))
(defun magit-get-svn-ref (&optional use-cache)
- "Get the best guess remote ref for the current git-svn based
-branch."
+ "Get the best guess remote ref for the current git-svn based branch.
+If USE-CACHE is non nil, use the cached information."
(let ((info (magit-get-svn-ref-info use-cache)))
(cdr (assoc 'local-ref info))))
@@ -2523,12 +2525,12 @@ branch."
(defun magit-rewrite-start (from &optional onto)
(interactive (list (magit-read-rev "Rewrite from" (magit-default-rev))))
(or (magit-everything-clean-p)
- (error "You have uncommitted changes."))
+ (error "You have uncommitted changes"))
(or (not (magit-read-rewrite-info))
- (error "Rewrite in progress."))
+ (error "Rewrite in progress"))
(let* ((orig (magit-git-string "rev-parse" "HEAD"))
(base (or (car (magit-commit-parents from))
- (error "Can't rewrite a commit without a parent, sorry.")))
+ (error "Can't rewrite a commit without a parent, sorry")))
(pending (magit-git-lines "rev-list" (concat base ".."))))
(magit-write-rewrite-info `((orig ,orig)
(pending ,@(mapcar #'list pending))))
@@ -2538,7 +2540,7 @@ branch."
(interactive)
(let* ((info (magit-read-rewrite-info)))
(or info
- (error "No rewrite in progress."))
+ (error "No rewrite in progress"))
(when (or noconfirm
(yes-or-no-p "Stop rewrite? "))
(magit-write-rewrite-info nil)
@@ -2549,9 +2551,9 @@ branch."
(let* ((info (magit-read-rewrite-info))
(orig (cadr (assq 'orig info))))
(or info
- (error "No rewrite in progress."))
+ (error "No rewrite in progress"))
(or (magit-everything-clean-p)
- (error "You have uncommitted changes."))
+ (error "You have uncommitted changes"))
(when (yes-or-no-p "Abort rewrite? ")
(magit-write-rewrite-info nil)
(magit-run-git "reset" "--hard" orig))))
@@ -2564,7 +2566,7 @@ branch."
(defun magit-rewrite-finish-step (first-p)
(let ((info (magit-read-rewrite-info)))
(or info
- (error "No rewrite in progress."))
+ (error "No rewrite in progress"))
(let* ((pending (cdr (assq 'pending info)))
(first-unused (find-if (lambda (p)
(not (plist-get (cdr p) 'used)))
@@ -2614,7 +2616,7 @@ branch."
(defun magit-push ()
(interactive)
(let* ((branch (or (magit-get-current-branch)
- (error "Don't push a detached head. That's gross.")))
+ (error "Don't push a detached head. That's gross")))
(branch-remote (magit-get "branch" branch "remote"))
(push-remote (if (or current-prefix-arg
(not branch-remote))
@@ -2724,7 +2726,7 @@ Prefix arg means justify as well."
(cond (author
;; XXX - this is a bit strict, probably.
(or (string-match "\\(.*\\) <\\(.*\\)>, \\(.*\\)" author)
- (error "Can't parse author string."))
+ (error "Can't parse author string"))
;; Shucks, setenv destroys the match data.
(let ((name (match-string 1 author))
(email (match-string 2 author))
@@ -2826,7 +2828,7 @@ Prefix arg means justify as well."
(defun magit-log-edit ()
(interactive)
(cond ((magit-rebase-info)
- (if (y-or-n-p "Rebase in progress. Continue it? ")
+ (if (y-or-n-p "Rebase in progress. Continue it? ")
(magit-run-git "rebase" "--continue")))
(t
(magit-log-edit-set-field 'tag nil)
@@ -2834,21 +2836,21 @@ Prefix arg means justify as well."
(not (magit-anything-staged-p)))
(cond ((eq magit-commit-all-when-nothing-staged 'ask-stage)
(if (and (not (magit-everything-clean-p))
- (y-or-n-p "Nothing staged. Stage everything now? "))
+ (y-or-n-p "Nothing staged. Stage everything now? "))
(magit-stage-all)))
((not (magit-log-edit-get-field 'commit-all))
(magit-log-edit-set-field
'commit-all
(if (or (eq magit-commit-all-when-nothing-staged t)
(y-or-n-p
- "Nothing staged. Commit all unstaged changes? "))
+ "Nothing staged. Commit all unstaged changes? "))
"yes" "no")))))
(magit-pop-to-log-edit "commit"))))
(defun magit-add-log ()
(interactive)
(cond ((magit-rebase-info)
- (if (y-or-n-p "Rebase in progress. Continue it? ")
+ (if (y-or-n-p "Rebase in progress. Continue it? ")
(magit-run-git "rebase" "--continue")))
(t
(let ((section (magit-current-section)))
@@ -2923,7 +2925,7 @@ Prefix arg means justify as well."
(magit-with-section stash 'stash
(magit-set-section-info stash)
(forward-line)))
- (forward-line))
+ (forward-line))
t)
(defun magit-wash-stashes ()
@@ -3013,7 +3015,7 @@ Prefix arg means justify as well."
(if nil-ok-p
commit
(or commit
- (error "No commit at point.")))))
+ (error "No commit at point")))))
(defun magit-apply-commit (commit &optional docommit noerase revert)
(let* ((parent-id (magit-choose-parent-id commit "cherry-pick"))
@@ -3207,7 +3209,7 @@ Prefix arg means justify as well."
(let ((ignored (magit-file-lines ignore-file)))
(cond ((member branch ignored)
(when (or (not edit)
- (y-or-n-p "Branch %s is already ignored. Unignore?"))
+ (y-or-n-p "Branch %s is already ignored. Unignore? "))
(setq ignored (delete branch ignored))))
(t
(setq ignored (append ignored (list branch)))))
@@ -3328,13 +3330,13 @@ Prefix arg means justify as well."
"Discard changes in region? "
"Discard hunk? "))
(magit-apply-hunk-item-reverse item "--index"))
- (error "Can't discard this hunk. Please unstage it first.")))
+ (error "Can't discard this hunk. Please unstage it first")))
((unstaged diff)
(magit-discard-diff item nil))
((staged diff)
(if (magit-file-uptodate-p (magit-diff-item-file item))
(magit-discard-diff item t)
- (error "Can't discard staged changes to this file. Please unstage it first.")))
+ (error "Can't discard staged changes to this file. Please unstage it first")))
((hunk)
(error "Can't discard this hunk"))
((diff)
@@ -3451,7 +3453,7 @@ Prefix arg means justify as well."
(error "Cannot resolve %s" file))
(with-current-buffer base-buffer
(if (string-match "^[0-9]+ [0-9a-f]+ 1" merge-status)
- (insert (magit-git-string "cat-file" "blob"
+ (insert (magit-git-string "cat-file" "blob"
(concat ":1:" file)))))
(with-current-buffer our-buffer
(if (string-match "^[0-9]+ [0-9a-f]+ 2" merge-status)
@@ -3494,4 +3496,6 @@ Prefix arg means justify as well."
((diff)
(magit-interactive-resolve (cadr info)))))
-(provide 'magit)
\ No newline at end of file
+(provide 'magit)
+
+;;; magit.el ends here
--
Rémi Vanicat
Rémi Vanicat
magit.el | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 105 insertions(+), 2 deletions(-)
diff --git a/magit.el b/magit.el
index 7632448..3576f5b 100644
--- a/magit.el
+++ b/magit.el
@@ -579,7 +579,8 @@ Many Magit faces inherit from this one by default."
parent title beginning end children hidden type info
needs-refresh-on-show)
-(defvar magit-top-section nil)
+(defvar magit-top-section nil
+ "The top section of the current buffer.")
(make-variable-buffer-local 'magit-top-section)
(put 'magit-top-section 'permanent-local t)
@@ -588,6 +589,12 @@ Many Magit faces inherit from this one by default."
(defvar magit-section-hidden-default nil)
(defun magit-new-section (title type)
+ "Create a new section with title TITLE and type TYPE in current buffer.
+
+If not `magit-top-section' exist, the new section will be the new top-section
+otherwise, the new-section will be a child of the current top-section.
+
+If TYPE is nil, the section won't be highlighted."
(let* ((s (make-magit-section :parent magit-top-section
:title title
:type type
@@ -603,6 +610,7 @@ Many Magit faces inherit from this one by default."
s))
(defun magit-cancel-section (section)
+ "Delete the section SECTION."
(delete-region (magit-section-beginning section)
(magit-section-end section))
(let ((parent (magit-section-parent section)))
@@ -612,6 +620,12 @@ Many Magit faces inherit from this one by default."
(setq magit-top-section nil))))
(defmacro magit-with-section (title type &rest body)
+ "Create a new section of title TITLE and type TYPE and evaluate BODY there.
+
+Sections create into BODY will be child of the new section.
+BODY must leave point at the end of the created section.
+
+If TYPE is nil, the section won't be highlighted."
(declare (indent 2))
(let ((s (gensym)))
`(let* ((,s (magit-new-section ,title ,type))
@@ -632,6 +646,7 @@ Many Magit faces inherit from this one by default."
flag))
(defmacro magit-create-buffer-sections (&rest body)
+ "Empty current buffer of text and magit's section, and then evaluate BODY."
(declare (indent 0))
`(let ((inhibit-read-only t))
(erase-buffer)
@@ -646,6 +661,7 @@ Many Magit faces inherit from this one by default."
(magit-section-hidden magit-top-section)))))
(defun magit-propertize-section (section)
+ "Add text-property needed for SECTION."
(put-text-property (magit-section-beginning section)
(magit-section-end section)
'magit-section section)
@@ -653,6 +669,7 @@ Many Magit faces inherit from this one by default."
(magit-propertize-section s)))
(defun magit-find-section (path top)
+ "Find in subsection of section TOP the section at the path PATH."
(if (null path)
top
(let ((sec (find-if (lambda (s) (equal (car path)
@@ -663,12 +680,16 @@ Many Magit faces inherit from this one by default."
nil))))
(defun magit-section-path (section)
+ "Return the path of SECTION."
(if (not (magit-section-parent section))
'()
(append (magit-section-path (magit-section-parent section))
(list (magit-section-title section)))))
+;; Dead code:
(defun magit-find-section-at (pos secs)
+ "Return the section at POS in SECS."
+ ;; Could use the text-property
(while (and secs
(not (and (<= (magit-section-beginning (car secs)) pos)
(< pos (magit-section-end (car secs))))))
@@ -679,12 +700,14 @@ Many Magit faces inherit from this one by default."
nil))
(defun magit-find-section-after (pos secs)
+ "Find the first section in the list SECS that begin after POS."
(while (and secs
(not (> (magit-section-beginning (car secs)) pos)))
(setq secs (cdr secs)))
(car secs))
(defun magit-find-section-before (pos secs)
+ "Find the last section in the list SECS that begin before POS."
(let ((prev nil))
(while (and secs
(not (> (magit-section-beginning (car secs)) pos)))
@@ -693,11 +716,26 @@ Many Magit faces inherit from this one by default."
prev))
(defun magit-current-section ()
+ "Return the magit section at point."
(or (get-text-property (point) 'magit-section)
magit-top-section))
(defun magit-insert-section (section-title-and-type
buffer-title washer cmd &rest args)
+ "Run CMD and put its result in a new section.
+
+SECTION-TITLE-AND-TYPE is either a string that is the title of the section
+or (TITLE . TYPE) where TITLE is the title of the section and TYPE is its type.
+
+If there is no type, or if type is nil, the section won't be highlighted.
+
+BUFFER-TITLE is the inserted title of the section
+
+WASHER is a function that will be run after CMD.
+The buffer will be narrowed to the inserted text.
+It should add sectioning as needed for magit interaction
+
+CMD is an external command that will be run with ARGS as arguments"
(let* ((body-beg nil)
(section-title (if (consp section-title-and-type)
(car section-title-and-type)
@@ -727,6 +765,9 @@ Many Magit faces inherit from this one by default."
(defun magit-git-section (section-title-and-type
buffer-title washer &rest args)
+ "Run git and put its result in a new section.
+
+see `magit-insert-section' for meaning of the arguments"
(apply #'magit-insert-section
section-title-and-type
buffer-title
@@ -735,6 +776,7 @@ Many Magit faces inherit from this one by default."
(append magit-git-standard-options args)))
(defun magit-next-section (section)
+ "Return the section that is after SECTION."
(let ((parent (magit-section-parent section)))
(if parent
(let ((next (cadr (memq section
@@ -743,6 +785,7 @@ Many Magit faces inherit from this one by default."
(magit-next-section parent))))))
(defun magit-goto-next-section ()
+ "Go to the next magit section."
(interactive)
(let* ((section (magit-current-section))
(next (or (and (not (magit-section-hidden section))
@@ -767,6 +810,7 @@ Many Magit faces inherit from this one by default."
(message "No next section"))))
(defun magit-prev-section (section)
+ "Return the section that is before SECTION."
(let ((parent (magit-section-parent section)))
(if parent
(let ((prev (cadr (memq section
@@ -780,6 +824,7 @@ Many Magit faces inherit from this one by default."
parent))))))
(defun magit-goto-previous-section ()
+ "Goto the previous magit section."
(interactive)
(let ((section (magit-current-section)))
(cond ((= (point) (magit-section-beginning section))
@@ -799,18 +844,23 @@ Many Magit faces inherit from this one by default."
(goto-char (magit-section-beginning (or prev section))))))))
(defun magit-goto-parent-section ()
+ "Goto the parent section."
(interactive)
(let ((parent (magit-section-parent (magit-current-section))))
(when parent
(goto-char (magit-section-beginning parent)))))
(defun magit-goto-section (path)
+ "Goto the section describe by PATH."
(let ((sec (magit-find-section path magit-top-section)))
(if sec
(goto-char (magit-section-beginning sec))
(message "No such section"))))
(defun magit-for-all-sections (func &optional top)
+ "Run FUNC on TOP and recursively on all its children.
+
+Default value for TOP is `magit-top-section'"
(let ((section (or top magit-top-section)))
(when section
(funcall func section)
@@ -818,6 +868,7 @@ Many Magit faces inherit from this one by default."
(magit-for-all-sections func c)))))
(defun magit-section-set-hidden (section hidden)
+ "Hide SECTION if HIDDEN is not nil, show it otherwise."
(setf (magit-section-hidden section) hidden)
(if (and (not hidden)
(magit-section-needs-refresh-on-show section))
@@ -834,29 +885,38 @@ Many Magit faces inherit from this one by default."
(magit-section-set-hidden c (magit-section-hidden c))))))
(defun magit-section-any-hidden (section)
+ "Return true if SECTION or any of its children is hidden."
(or (magit-section-hidden section)
(some #'magit-section-any-hidden (magit-section-children section))))
(defun magit-section-collapse (section)
+ "Show SECTION and hide all its children."
(dolist (c (magit-section-children section))
(setf (magit-section-hidden c) t))
(magit-section-set-hidden section nil))
(defun magit-section-expand (section)
+ "Show SECTION and all its children."
(dolist (c (magit-section-children section))
(setf (magit-section-hidden c) nil))
(magit-section-set-hidden section nil))
(defun magit-section-expand-all-aux (section)
+ "Show recursively all SECTION's children."
(dolist (c (magit-section-children section))
(setf (magit-section-hidden c) nil)
(magit-section-expand-all-aux c)))
(defun magit-section-expand-all (section)
+ "Show SECTION and all its children."
(magit-section-expand-all-aux section)
(magit-section-set-hidden section nil))
(defun magit-section-hideshow (flag-or-func)
+ "Show or hide current section depending on FLAG-OR-FUNC.
+
+If FLAG-OR-FUNC is a function, it will be ran on current section
+IF FLAG-OR-FUNC is a Boolean value, the section will be hidden if its true, shown otherwise"
(let ((section (magit-current-section)))
(when (magit-section-parent section)
(goto-char (magit-section-beginning section))
@@ -870,14 +930,17 @@ Many Magit faces inherit from this one by default."
(magit-section-hideshow nil))
(defun magit-hide-section ()
+ "Hide current section."
(interactive)
(magit-section-hideshow t))
(defun magit-collapse-section ()
+ "Hide all subsection of current section."
(interactive)
(magit-section-hideshow #'magit-section-collapse))
(defun magit-expand-section ()
+ "Show all subsection of current section."
(interactive)
(magit-section-hideshow #'magit-section-expand))
@@ -889,12 +952,14 @@ Many Magit faces inherit from this one by default."
(magit-toggle-section))
(defun magit-toggle-section ()
+ "Toggle hidden status of current section."
(interactive)
(magit-section-hideshow
(lambda (s)
(magit-section-set-hidden s (not (magit-section-hidden s))))))
(defun magit-expand-collapse-section ()
+ "Toggle hidden status of subsections of current section."
(interactive)
(magit-section-hideshow
(lambda (s)
@@ -904,6 +969,11 @@ Many Magit faces inherit from this one by default."
(magit-section-collapse s))))))
(defun magit-cycle-section ()
+ "Cycle between expanded, hidden and collapsed state for current section.
+
+Hidden: only the first line of the section is shown
+Collapsed: only the first line of the subsection is shown
+Expanded: everything is shown."
(interactive)
(magit-section-hideshow
(lambda (s)
@@ -915,7 +985,9 @@ Many Magit faces inherit from this one by default."
(magit-section-expand s))))))
(defun magit-section-lineage (s)
- (and s (cons s (magit-section-lineage (magit-section-parent s)))))
+ "Return list of parent, grand-parents... for section S."
+ (when s
+ (cons s (magit-section-lineage (magit-section-parent s)))))
(defun magit-section-show-level (section level threshold path)
(magit-section-set-hidden section (>= level threshold))
@@ -926,6 +998,9 @@ Many Magit faces inherit from this one by default."
(magit-section-show-level c (1+ level) threshold nil)))))
(defun magit-show-level (level all)
+ "Show section whose level is less than LEVEL, hide the others.
+If ALL is non nil, do this in all sections,
+otherwise do it only on ancestors and descendants of current section."
(magit-with-refresh
(if all
(magit-section-show-level magit-top-section 0 level nil)
@@ -933,18 +1008,28 @@ Many Magit faces inherit from this one by default."
(magit-section-show-level (car path) 0 level (cdr path))))))
(defun magit-show-only-files ()
+ "Show section that are files, but not there subsection.
+
+Do this in on ancestors and descendants of current section."
(interactive)
(if (eq magit-submode 'status)
(call-interactively 'magit-show-level-2)
(call-interactively 'magit-show-level-1)))
(defun magit-show-only-files-all ()
+ "Show section that are files, but not there subsection.
+
+Do this for all sections"
(interactive)
(if (eq magit-submode 'status)
(call-interactively 'magit-show-level-2-all)
(call-interactively 'magit-show-level-1-all)))
(defmacro magit-define-level-shower-1 (level all)
+ "Define an interactive function to show function of level LEVEL.
+
+If ALL is non nil, this function will affect all section,
+otherwise it will affect only ancestors and descendants of current section."
(let ((fun (intern (format "magit-show-level-%s%s"
level (if all "-all" ""))))
(doc (format "Show sections on level %s." level)))
@@ -954,11 +1039,16 @@ Many Magit faces inherit from this one by default."
(magit-show-level ,level ,all))))
(defmacro magit-define-level-shower (level)
+ "Define two interactive function to show function of level LEVEL.
+one for all, one for current lineage."
`(progn
(magit-define-level-shower-1 ,level nil)
(magit-define-level-shower-1 ,level t)))
(defmacro magit-define-section-jumper (sym title)
+ "Define an interactive function to go to section SYM.
+
+TITLE is the displayed title of the section."
(let ((fun (intern (format "magit-jump-to-%s" sym)))
(doc (format "Jump to section `%s'." title)))
`(defun ,fun ()
@@ -971,6 +1061,7 @@ Many Magit faces inherit from this one by default."
(defvar magit-highlighted-section nil)
(defun magit-highlight-section ()
+ "Highlight current section if it have a type."
(let ((section (magit-current-section)))
(when (not (eq section magit-highlighted-section))
(setq magit-highlighted-section section)
@@ -1008,6 +1099,15 @@ Many Magit faces inherit from this one by default."
(magit-prefix-p (cdr prefix) (cdr list))))))
(defmacro magit-section-case (head &rest clauses)
+ "Make different action depending of current section.
+
+HEAD is (SECTION INFO &optional OPNAME),
+ SECTION will be bind to the current section,
+ INFO will be bind to the info's of the current section,
+ OPNAME is a string that will be used to describe current action,
+
+CLAUSES is a list of CLAUSE, each clause is (SECTION-TYPE &BODY)
+where SECTION-TYPE describe section where BODY will be run."
(declare (indent 1))
(let ((section (car head))
(info (cadr head))
@@ -1041,6 +1141,9 @@ Many Magit faces inherit from this one by default."
(magit-section-case ,head ,@clauses)))
(defun magit-wash-sequence (func)
+ "Run FUNC until end of buffer is reached.
+
+FUNC should leave point at the end of the modified region"
(while (and (not (eobp))
(funcall func))))
--
Rémi Vanicat
Philip Jackson
Rémi Vanicat wrote:
> I send Two patch with no new code:
> the first fix style error in comment, docstring and error message
> the second add docstring to a bunch of magit's function (the one
> referring to sectioning.
Applied.
Cheers,
Phil