From 168609cc1b7b10d71e08b3166233026b1f0c8794 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 24 Apr 2015 11:24:56 +0300 Subject: [PATCH] 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 file changed, 34 insertions(+), 26 deletions(-) diff --git a/src/textprop.c b/src/textprop.c index 108c226a432..f50ef08a223 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. */) -- 2.39.2