From 7c80c1019905bcae01b08f0f32ab6059f1044a27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Vanicat?= Date: Sat, 27 Mar 2010 12:21:11 +0100 Subject: [PATCH] Added docstring for section's function --- magit.el | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 105 insertions(+), 2 deletions(-) diff --git a/magit.el b/magit.el index 76324487..3576f5b8 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))))