From 78908644131e70f20de28fed08ef4dc2878878a3 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 16 Dec 2017 12:15:06 +0200
Subject: [PATCH] Improve documentation of 'invisible-p'

* doc/lispref/display.texi (Invisible Text): Document the return
value of 'invisible-p'.

* src/xdisp.c (Finvisible_p): Rename the argument POS.  Doc fix.
(Bug#29721)
---
 doc/lispref/display.texi |  7 ++++++-
 src/xdisp.c              | 28 +++++++++++++++++-----------
 2 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 7af8d9efb7c..50069e3d1da 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -929,13 +929,18 @@ major mode should use the mode's own name as an element of
 
 @defun invisible-p pos-or-prop
 If @var{pos-or-prop} is a marker or number, this function returns a
-non-@code{nil} value if the text at that position is invisible.
+non-@code{nil} value if the text at that position is currently
+invisible.
 
 If @var{pos-or-prop} is any other kind of Lisp object, that is taken
 to mean a possible value of the @code{invisible} text or overlay
 property.  In that case, this function returns a non-@code{nil} value
 if that value would cause text to become invisible, based on the
 current value of @code{buffer-invisibility-spec}.
+
+The return value of this function is @code{t} if the text would be
+completely hidden on display, or a non-@code{nil}, non-@code{t} value
+if the text would be replaced by an ellipsis.
 @end defun
 
 @vindex line-move-ignore-invisible
diff --git a/src/xdisp.c b/src/xdisp.c
index 0a37013c560..7601e26a902 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -25086,19 +25086,25 @@ invisible_prop (Lisp_Object propval, Lisp_Object list)
 }
 
 DEFUN ("invisible-p", Finvisible_p, Sinvisible_p, 1, 1, 0,
-       doc: /* Non-nil if the property makes the text invisible.
-POS-OR-PROP can be a marker or number, in which case it is taken to be
-a position in the current buffer and the value of the `invisible' property
-is checked; or it can be some other value, which is then presumed to be the
-value of the `invisible' property of the text of interest.
-The non-nil value returned can be t for truly invisible text or something
-else if the text is replaced by an ellipsis.  */)
-  (Lisp_Object pos_or_prop)
+       doc: /* Non-nil if text properties at POS cause text there to be currently invisible.
+POS should be a marker or a buffer position; the value of the `invisible'
+property at that position in the current buffer is examined.
+POS can also be the actual value of the `invisible' text or overlay
+property of the text of interest, in which case the value itself is
+examined.
+
+The non-nil value returned can be t for currently invisible text that is
+entirely hidden on display, or some other non-nil, non-t value if the
+text is replaced by an ellipsis.
+
+Note that whether text with `invisible' property is actually hidden on
+display may depend on `buffer-invisibility-spec', which see.  */)
+  (Lisp_Object pos)
 {
   Lisp_Object prop
-    = (NATNUMP (pos_or_prop) || MARKERP (pos_or_prop)
-       ? Fget_char_property (pos_or_prop, Qinvisible, Qnil)
-       : pos_or_prop);
+    = (NATNUMP (pos) || MARKERP (pos)
+       ? Fget_char_property (pos, Qinvisible, Qnil)
+       : pos);
   int invis = TEXT_PROP_MEANS_INVISIBLE (prop);
   return (invis == 0 ? Qnil
 	  : invis == 1 ? Qt
-- 
2.39.2