[Emacs-diffs] master 9eda79f: button-* function doc string clarifications

[Lars Ingebrigtsen]

branch: master
commit 9eda79fc8c2b3e66ff6934ef0a8f2b747c27d245
Author: Jiajie Chen <address@hidden>
Commit: Lars Ingebrigtsen <address@hidden>

    button-* function doc string clarifications
    
    * lisp/button.el (button-start, button-end, button-get)
    (button-put, button-label): Have the doc string mention that they
    have to be called from the current buffer (bug#23909).
    
    Copyright-paperwork-exempt: yes
---
 lisp/button.el | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/lisp/button.el b/lisp/button.el
index 04e77ca..ac6af0b 100644
--- a/lisp/button.el
+++ b/lisp/button.el
@@ -169,7 +169,9 @@ changes to a supertype are not reflected in its subtypes)."
 ;;; Button properties and other attributes
 
 (defun button-start (button)
-  "Return the position at which BUTTON starts."
+  "Return the position at which BUTTON starts.
+
+This function only works when BUTTON is in the current buffer."
   (if (overlayp button)
       (overlay-start button)
     ;; Must be a text-property button.
@@ -177,7 +179,9 @@ changes to a supertype are not reflected in its subtypes)."
        (point-min))))
 
 (defun button-end (button)
-  "Return the position at which BUTTON ends."
+  "Return the position at which BUTTON ends.
+
+This function only works when BUTTON is in the current buffer."
   (if (overlayp button)
       (overlay-end button)
     ;; Must be a text-property button.
@@ -185,7 +189,9 @@ changes to a supertype are not reflected in its subtypes)."
        (point-max))))
 
 (defun button-get (button prop)
-  "Get the property of button BUTTON named PROP."
+  "Get the property of button BUTTON named PROP.
+
+This function only works when BUTTON is in the current buffer."
   (cond ((overlayp button)
         (overlay-get button prop))
        ((button--area-button-p button)
@@ -197,7 +203,9 @@ changes to a supertype are not reflected in its subtypes)."
         (get-text-property button prop))))
 
 (defun button-put (button prop val)
-  "Set BUTTON's PROP property to VAL."
+  "Set BUTTON's PROP property to VAL.
+
+This function only works when BUTTON is in the current buffer."
   ;; Treat some properties specially.
   (cond ((memq prop '(type :type))
          ;; We translate a `type' property to a `category' property,
@@ -235,7 +243,9 @@ overlay, a buffer position, or (for buttons in the 
mode-line or
 header-line) a string.
 
 If BUTTON has a `button-data' value, call the function with this
-value instad of BUTTON."
+value instad of BUTTON.
+
+This function only works when BUTTON is in the current buffer."
   (let ((action (or (and use-mouse-action (button-get button 'mouse-action))
                    (button-get button 'action)))
         (data (button-get button 'button-data)))
@@ -247,7 +257,9 @@ value instad of BUTTON."
       (funcall action (or data button)))))
 
 (defun button-label (button)
-  "Return BUTTON's text label."
+  "Return BUTTON's text label.
+
+This function only works when BUTTON is in the current buffer."
   (if (button--area-button-p button)
       (substring-no-properties (button--area-button-string button))
     (buffer-substring-no-properties (button-start button)