[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] master 168609c: Clarify doc strings of functions that sear
From: |
Eli Zaretskii |
Subject: |
[Emacs-diffs] master 168609c: Clarify doc strings of functions that search for properties |
Date: |
Fri, 24 Apr 2015 08:27:06 +0000 |
branch: master
commit 168609cc1b7b10d71e08b3166233026b1f0c8794
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>
Clarify doc strings of functions that search for properties
* src/textprop.c (Fnext_char_property_change)
(Fprevious_char_property_change)
(Fnext_single_char_property_change)
(Fprevious_single_char_property_change, Fnext_property_change)
(Fnext_single_property_change, Fprevious_property_change)
(Fprevious_single_property_change): Clarify doc strings wrt return
value and the optional LIMIT argument. (Bug#20411)
---
src/textprop.c | 60 +++++++++++++++++++++++++++++++------------------------
1 files changed, 34 insertions(+), 26 deletions(-)
diff --git a/src/textprop.c b/src/textprop.c
index 108c226..f50ef08 100644
--- a/src/textprop.c
+++ b/src/textprop.c
@@ -711,11 +711,12 @@ DEFUN ("next-char-property-change",
Fnext_char_property_change,
This scans characters forward in the current buffer from POSITION till
it finds a change in some text property, or the beginning or end of an
overlay, and returns the position of that.
-If none is found up to (point-max), the function returns (point-max).
+If none is found, and LIMIT is nil or omitted, the function
+returns (point-max).
-If the optional second argument LIMIT is non-nil, don't search
-past position LIMIT; return LIMIT if nothing is found before LIMIT.
-LIMIT is a no-op if it is greater than (point-max). */)
+If the optional second argument LIMIT is non-nil, the function doesn't
+search past position LIMIT, and returns LIMIT if nothing is found
+before LIMIT. LIMIT is a no-op if it is greater than (point-max). */)
(Lisp_Object position, Lisp_Object limit)
{
Lisp_Object temp;
@@ -736,11 +737,12 @@ DEFUN ("previous-char-property-change",
Fprevious_char_property_change,
Scans characters backward in the current buffer from POSITION till it
finds a change in some text property, or the beginning or end of an
overlay, and returns the position of that.
-If none is found since (point-min), the function returns (point-min).
+If none is found, and LIMIT is nil or imitted, the function
+returns (point-min).
-If the optional second argument LIMIT is non-nil, don't search
-past position LIMIT; return LIMIT if nothing is found before LIMIT.
-LIMIT is a no-op if it is less than (point-min). */)
+If the optional second argument LIMIT is non-nil, the function doesn't
+search before position LIMIT, and returns LIMIT if nothing is found
+before LIMIT. LIMIT is a no-op if it is less than (point-min). */)
(Lisp_Object position, Lisp_Object limit)
{
Lisp_Object temp;
@@ -765,14 +767,15 @@ If the optional third argument OBJECT is a buffer (or
nil, which means
the current buffer), POSITION is a buffer position (integer or marker).
If OBJECT is a string, POSITION is a 0-based index into it.
-In a string, scan runs to the end of the string.
-In a buffer, it runs to (point-max), and the value cannot exceed that.
+In a string, scan runs to the end of the string, unless LIMIT is non-nil.
+In a buffer, if LIMIT is nil or omitted, it runs to (point-max), and the
+value cannot exceed that.
+If the optional fourth argument LIMIT is non-nil, don't search
+past position LIMIT; return LIMIT if nothing is found before LIMIT.
The property values are compared with `eq'.
If the property is constant all the way to the end of OBJECT, return the
-last valid position in OBJECT.
-If the optional fourth argument LIMIT is non-nil, don't search
-past position LIMIT; return LIMIT if nothing is found before LIMIT. */)
+last valid position in OBJECT. */)
(Lisp_Object position, Lisp_Object prop, Lisp_Object object, Lisp_Object
limit)
{
if (STRINGP (object))
@@ -849,14 +852,15 @@ If the optional third argument OBJECT is a buffer (or
nil, which means
the current buffer), POSITION is a buffer position (integer or marker).
If OBJECT is a string, POSITION is a 0-based index into it.
-In a string, scan runs to the start of the string.
-In a buffer, it runs to (point-min), and the value cannot be less than that.
+In a string, scan runs to the start of the string, unless LIMIT is non-nil.
+In a buffer, if LIMIT is nil or omitted, it runs to (point-min), and the
+value cannot be less than that.
+If the optional fourth argument LIMIT is non-nil, don't search back past
+position LIMIT; return LIMIT if nothing is found before reaching LIMIT.
The property values are compared with `eq'.
If the property is constant all the way to the start of OBJECT, return the
-first valid position in OBJECT.
-If the optional fourth argument LIMIT is non-nil, don't search back past
-position LIMIT; return LIMIT if nothing is found before reaching LIMIT. */)
+first valid position in OBJECT. */)
(Lisp_Object position, Lisp_Object prop, Lisp_Object object, Lisp_Object
limit)
{
if (STRINGP (object))
@@ -940,8 +944,9 @@ a change in some text property, then returns the position
of the change.
If the optional second argument OBJECT is a buffer (or nil, which means
the current buffer), POSITION is a buffer position (integer or marker).
If OBJECT is a string, POSITION is a 0-based index into it.
-Return nil if the property is constant all the way to the end of OBJECT.
-If the value is non-nil, it is a position greater than POSITION, never equal.
+Return nil if LIMIT is nil or omitted, and the property is constant all
+the way to the end of OBJECT; if the value is non-nil, it is a position
+greater than POSITION, never equal.
If the optional third argument LIMIT is non-nil, don't search
past position LIMIT; return LIMIT if nothing is found before LIMIT. */)
@@ -1005,8 +1010,9 @@ If the optional third argument OBJECT is a buffer (or
nil, which means
the current buffer), POSITION is a buffer position (integer or marker).
If OBJECT is a string, POSITION is a 0-based index into it.
The property values are compared with `eq'.
-Return nil if the property is constant all the way to the end of OBJECT.
-If the value is non-nil, it is a position greater than POSITION, never equal.
+Return nil if LIMIT is nil or omitted, and the property is constant all
+the way to the end of OBJECT; if the value is non-nil, it is a position
+greater than POSITION, never equal.
If the optional fourth argument LIMIT is non-nil, don't search
past position LIMIT; return LIMIT if nothing is found before LIMIT. */)
@@ -1052,8 +1058,9 @@ a change in some text property, then returns the position
of the change.
If the optional second argument OBJECT is a buffer (or nil, which means
the current buffer), POSITION is a buffer position (integer or marker).
If OBJECT is a string, POSITION is a 0-based index into it.
-Return nil if the property is constant all the way to the start of OBJECT.
-If the value is non-nil, it is a position less than POSITION, never equal.
+Return nil if LIMIT is nil or omitted, and the property is constant all
+the way to the start of OBJECT; if the value is non-nil, it is a position
+less than POSITION, never equal.
If the optional third argument LIMIT is non-nil, don't search
back past position LIMIT; return LIMIT if nothing is found until LIMIT. */)
@@ -1100,8 +1107,9 @@ If the optional third argument OBJECT is a buffer (or
nil, which means
the current buffer), POSITION is a buffer position (integer or marker).
If OBJECT is a string, POSITION is a 0-based index into it.
The property values are compared with `eq'.
-Return nil if the property is constant all the way to the start of OBJECT.
-If the value is non-nil, it is a position less than POSITION, never equal.
+Return nil if LIMIT is nil or omitted, and the property is constant all
+the way to the start of OBJECT; if the value is non-nil, it is a position
+less than POSITION, never equal.
If the optional fourth argument LIMIT is non-nil, don't search
back past position LIMIT; return LIMIT if nothing is found until LIMIT. */)
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] master 168609c: Clarify doc strings of functions that search for properties,
Eli Zaretskii <=