Added docstring for section's function

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))))