From 9eda79fc8c2b3e66ff6934ef0a8f2b747c27d245 Mon Sep 17 00:00:00 2001
From: Jiajie Chen <jiegec@qq.com>
Date: Sat, 12 Oct 2019 21:47:47 +0200
Subject: [PATCH] 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 04e77ca904f..ac6af0be4f8 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)
-- 
2.39.5