branch: elpa/magit
commit 3ad94012b0f570809c52eb3323fa1436e180984e
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
magit-section-ident-value: Improve docstring
---
lisp/magit-log.el | 20 ++++++++++----------
lisp/magit-section.el | 19 +++++++++++--------
2 files changed, 21 insertions(+), 18 deletions(-)
diff --git a/lisp/magit-log.el b/lisp/magit-log.el
index f48848160f..9a2e46a6ab 100644
--- a/lisp/magit-log.el
+++ b/lisp/magit-log.el
@@ -1884,11 +1884,11 @@ keymap is the parent of their keymaps."
"<1>" (magit-menu-item "Visit diff" #'magit-diff-dwim))
(cl-defmethod magit-section-ident-value ((section magit-unpulled-section))
- "\"..@{push}\" cannot be used as the value because that is
-ambiguous if `push.default' does not allow a 1:1 mapping, and
-many commands would fail because of that. But here that does
-not matter and we need an unique value so we use that string
-in the pushremote case."
+ "Return \"..@{push}\".
+\"..@{push}\" cannot be used as the value because that is ambiguous
+if `push.default' does not allow a 1:1 mapping, and many commands
+would fail because of that. But here that does not matter and we
+need an unique value, so we use that string in the pushremote case."
(let ((value (oref section value)))
(if (equal value "..@{upstream}") value "..@{push}")))
@@ -1925,11 +1925,11 @@ in the pushremote case."
(magit-log-insert-child-count))))
(cl-defmethod magit-section-ident-value ((section magit-unpushed-section))
- "\"..@{push}\" cannot be used as the value because that is
-ambiguous if `push.default' does not allow a 1:1 mapping, and
-many commands would fail because of that. But here that does
-not matter and we need an unique value so we use that string
-in the pushremote case."
+ "Return \"..@{push}\".
+\"..@{push}\" cannot be used as the value because that is ambiguous
+if `push.default' does not allow a 1:1 mapping, and many commands
+would fail because of that. But here that does not matter and we
+need an unique value, so we use that string in the pushremote case."
(let ((value (oref section value)))
(if (equal value "@{upstream}..") value "@{push}..")))
diff --git a/lisp/magit-section.el b/lisp/magit-section.el
index d737157c13..e5a43d6eea 100644
--- a/lisp/magit-section.el
+++ b/lisp/magit-section.el
@@ -552,24 +552,27 @@ The return value has the form ((TYPE . VALUE)...)."
This is used to correlate different incarnations of the same
section, see `magit-section-ident' and `magit-get-section'.
-Sections whose values that are not constant and/or unique should
-implement a method that return a value that can be used for this
-purpose.")
+Sections whose values are not constant and/or unique should
+implement a method that return a value that can be used for
+thispurpose.")
(cl-defmethod magit-section-ident-value ((section magit-section))
"Return the value unless it is an object.
-Different object incarnations representing the same value tend to not be
-equal, so call this generic function on the object itself to determine a
-constant value."
+Different object incarnations representing the same value tend to
+not be equal, so call this generic function on the object itself
+to determine a constant value."
(let ((value (oref section value)))
(if (eieio-object-p value)
(magit-section-ident-value value)
value)))
(cl-defmethod magit-section-ident-value ((object eieio-default-superclass))
- "Simply return the object itself. That likely isn't
-good enough, so you need to implement your own method."
+ "For values that are objects, simply return the object itself.
+Two objects that represent the same entity are not `equal'. So if
+the values of the objects of a certain section class are themselves
+objects, then a method has to be defined for objects of one of the
+involved classes."
object)
(defun magit-get-section (ident &optional root)
