changeset 49247:5856f0179746

(Ftext_properties_at, 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, Fadd_text_properties) (Fput_text_property, Fset_text_properties) (Fremove_text_properties, Fremove_list_of_text_properties) (Ftext_property_any, Ftext_property_not_all): Clarify doc strings.

--- a/src/textprop.c	Tue Jan 14 23:12:31 2003 +0000
+++ b/src/textprop.c	Tue Jan 14 23:13:05 2003 +0000
@@ -177,7 +177,7 @@
 
   if (NULL_INTERVAL_P (i))
     return (force ? create_root_interval (object) : i);
-    
+
   return find_interval (i, searchpos);
 }
 
@@ -526,7 +526,7 @@
 }
 #endif
 
-/* Returns the interval of POSITION in OBJECT. 
+/* Returns the interval of POSITION in OBJECT.
    POSITION is BEG-based.  */
 
 INTERVAL
@@ -563,15 +563,16 @@
     args_out_of_range (make_number (position), make_number (position));
   if (beg == end || NULL_INTERVAL_P (i))
     return NULL_INTERVAL;
-    
+
   return find_interval (i, position);
 }
 
 DEFUN ("text-properties-at", Ftext_properties_at,
        Stext_properties_at, 1, 2, 0,
        doc: /* Return the list of properties of the character at POSITION in OBJECT.
-OBJECT is the string or buffer to look for the properties in;
-nil means the current buffer.
+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.
 If POSITION is at the end of OBJECT, the value is nil.  */)
      (position, object)
      Lisp_Object position, object;
@@ -706,9 +707,9 @@
 DEFUN ("next-char-property-change", Fnext_char_property_change,
        Snext_char_property_change, 1, 2, 0,
        doc: /* Return the position of next text property or overlay change.
-This scans characters forward 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.
+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, the function returns (point-max).
 
 If the optional third argument LIMIT is non-nil, don't search
@@ -731,9 +732,9 @@
 DEFUN ("previous-char-property-change", Fprevious_char_property_change,
        Sprevious_char_property_change, 1, 2, 0,
        doc: /* Return the position of previous text property or overlay change.
-Scans characters backward 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.
+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, the function returns (point-max).
 
 If the optional third argument LIMIT is non-nil, don't search
@@ -759,7 +760,10 @@
        doc: /* Return the position of next text property or overlay change for a specific property.
 Scans characters forward from POSITION till it finds
 a change in the PROP property, then returns the position of the change.
-The optional third argument OBJECT is the string or buffer to scan.
+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'.
 If the property is constant all the way to the end of OBJECT, return the
 last valid position in OBJECT.
@@ -786,7 +790,7 @@
 
       if (! NILP (object))
 	CHECK_BUFFER (object);
-      
+
       if (BUFFERP (object) && current_buffer != XBUFFER (object))
 	{
 	  record_unwind_protect (Fset_buffer, Fcurrent_buffer ());
@@ -794,7 +798,7 @@
 	}
 
       initial_value = Fget_char_property (position, prop, object);
-      
+
       if (NILP (limit))
 	XSETFASTINT (limit, BUF_ZV (current_buffer));
       else
@@ -825,7 +829,10 @@
        doc: /* Return the position of previous text property or overlay change for a specific property.
 Scans characters backward from POSITION till it finds
 a change in the PROP property, then returns the position of the change.
-The optional third argument OBJECT is the string or buffer to scan.
+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'.
 If the property is constant all the way to the start of OBJECT, return the
 first valid position in OBJECT.
@@ -851,13 +858,13 @@
 
       if (! NILP (object))
 	CHECK_BUFFER (object);
-      
+
       if (BUFFERP (object) && current_buffer != XBUFFER (object))
 	{
 	  record_unwind_protect (Fset_buffer, Fcurrent_buffer ());
 	  Fset_buffer (object);
 	}
-      
+
       if (NILP (limit))
 	XSETFASTINT (limit, BUF_BEGV (current_buffer));
       else
@@ -870,7 +877,7 @@
 	  Lisp_Object initial_value =
 	    Fget_char_property (make_number (XFASTINT (position) - 1),
 				prop, object);
-      
+
 	  for (;;)
 	    {
 	      position = Fprevious_char_property_change (position, limit);
@@ -903,7 +910,9 @@
        doc: /* Return the position of next property change.
 Scans characters forward from POSITION in OBJECT till it finds
 a change in some text property, then returns the position of the change.
-The optional second argument OBJECT is the string or buffer to scan.
+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.
 
@@ -930,7 +939,7 @@
 	next = i;
       else
 	next = next_interval (i);
-	
+
       if (NULL_INTERVAL_P (next))
 	XSETFASTINT (position, (STRINGP (object)
 				? SCHARS (object)
@@ -999,7 +1008,9 @@
        doc: /* Return the position of next property change for a specific property.
 Scans characters forward from POSITION till it finds
 a change in the PROP property, then returns the position of the change.
-The optional third argument OBJECT is the string or buffer to scan.
+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.
@@ -1024,7 +1035,7 @@
 
   here_val = textget (i->plist, prop);
   next = next_interval (i);
-  while (! NULL_INTERVAL_P (next) 
+  while (! NULL_INTERVAL_P (next)
 	 && EQ (here_val, textget (next->plist, prop))
 	 && (NILP (limit) || next->position < XFASTINT (limit)))
     next = next_interval (next);
@@ -1046,7 +1057,9 @@
        doc: /* Return the position of previous property change.
 Scans characters backwards from POSITION in OBJECT till it finds
 a change in some text property, then returns the position of the change.
-The optional second argument OBJECT is the string or buffer to scan.
+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.
 
@@ -1091,7 +1104,9 @@
        doc: /* Return the position of previous property change for a specific property.
 Scans characters backward from POSITION till it finds
 a change in the PROP property, then returns the position of the change.
-The optional third argument OBJECT is the string or buffer to scan.
+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.
@@ -1142,9 +1157,10 @@
        Sadd_text_properties, 3, 4, 0,
        doc: /* Add properties to the text from START to END.
 The third argument PROPERTIES is a property list
-specifying the property values to add.
-The optional fourth argument, OBJECT,
-is the string or buffer containing the text.
+specifying the property values to add.  If the optional fourth argument
+OBJECT is a buffer (or nil, which means the current buffer),
+START and END are buffer positions (integers or markers).
+If OBJECT is a string, START and END are 0-based indices into it.
 Return t if any property value actually changed, nil otherwise.  */)
      (start, end, properties, object)
      Lisp_Object start, end, properties, object;
@@ -1251,8 +1267,9 @@
        doc: /* Set one property of the text from START to END.
 The third and fourth arguments PROPERTY and VALUE
 specify the property to add.
-The optional fifth argument, OBJECT,
-is the string or buffer containing the text.  */)
+If the optional fifth argument OBJECT is a buffer (or nil, which means
+the current buffer), START and END are buffer positions (integers or
+markers).  If OBJECT is a string, START and END are 0-based indices into it.  */)
      (start, end, property, value, object)
      Lisp_Object start, end, property, value, object;
 {
@@ -1266,9 +1283,9 @@
        Sset_text_properties, 3, 4, 0,
        doc: /* Completely replace properties of text from START to END.
 The third argument PROPERTIES is the new property list.
-The optional fourth argument, OBJECT,
-is the string or buffer containing the text.
-If OBJECT is omitted or nil, it defaults to the current buffer.
+If the optional fourth argument OBJECT is a buffer (or nil, which means
+the current buffer), START and END are buffer positions (integers or
+markers).  If OBJECT is a string, START and END are 0-based indices into it.
 If PROPERTIES is nil, the effect is to remove all properties from
 the designated part of OBJECT.  */)
      (start, end, properties, object)
@@ -1436,9 +1453,12 @@
 The third argument PROPERTIES is a property list
 whose property names specify the properties to remove.
 \(The values stored in PROPERTIES are ignored.)
-The optional fourth argument, OBJECT,
-is the string or buffer containing the text.
-Return t if any property was actually removed, nil otherwise.  */)
+If the optional fourth argument OBJECT is a buffer (or nil, which means
+the current buffer), START and END are buffer positions (integers or
+markers).  If OBJECT is a string, START and END are 0-based indices into it.
+Return t if any property was actually removed, nil otherwise.
+
+Use set-text-properties if you want to remove all text properties.  */)
      (start, end, properties, object)
      Lisp_Object start, end, properties, object;
 {
@@ -1521,8 +1541,9 @@
        Sremove_list_of_text_properties, 3, 4, 0,
        doc: /* Remove some properties from text from START to END.
 The third argument LIST-OF-PROPERTIES is a list of property names to remove.
-The optional fourth argument, OBJECT,
-is the string or buffer containing the text, defaulting to the current buffer.
+If the optional fourth argument OBJECT is a buffer (or nil, which means
+the current buffer), START and END are buffer positions (integers or
+markers).  If OBJECT is a string, START and END are 0-based indices into it.
 Return t if any property was actually removed, nil otherwise.  */)
      (start, end, list_of_properties, object)
      Lisp_Object start, end, list_of_properties, object;
@@ -1609,8 +1630,9 @@
        doc: /* Check text from START to END for property PROPERTY equalling VALUE.
 If so, return the position of the first character whose property PROPERTY
 is `eq' to VALUE.  Otherwise return nil.
-The optional fifth argument, OBJECT, is the string or buffer
-containing the text.  */)
+If the optional fifth argument OBJECT is a buffer (or nil, which means
+the current buffer), START and END are buffer positions (integers or
+markers).  If OBJECT is a string, START and END are 0-based indices into it.  */)
      (start, end, property, value, object)
      Lisp_Object start, end, property, value, object;
 {
@@ -1645,8 +1667,9 @@
        doc: /* Check text from START to END for property PROPERTY not equalling VALUE.
 If so, return the position of the first character whose property PROPERTY
 is not `eq' to VALUE.  Otherwise, return nil.
-The optional fifth argument, OBJECT, is the string or buffer
-containing the text.  */)
+If the optional fifth argument OBJECT is a buffer (or nil, which means
+the current buffer), START and END are buffer positions (integers or
+markers).  If OBJECT is a string, START and END are 0-based indices into it.  */)
      (start, end, property, value, object)
      Lisp_Object start, end, property, value, object;
 {
@@ -1850,23 +1873,23 @@
   Lisp_Object result;
 
   result = Qnil;
-  
+
   i = validate_interval_range (object, &start, &end, soft);
   if (!NULL_INTERVAL_P (i))
     {
       int s = XINT (start);
       int e = XINT (end);
-      
+
       while (s < e)
 	{
 	  int interval_end, len;
 	  Lisp_Object plist;
-	  
+
 	  interval_end = i->position + LENGTH (i);
 	  if (interval_end > e)
 	    interval_end = e;
 	  len = interval_end - s;
-	  
+
 	  plist = i->plist;
 
 	  if (!NILP (prop))
@@ -1882,14 +1905,14 @@
 				   Fcons (make_number (s + len),
 					  Fcons (plist, Qnil))),
 			    result);
-	  
+
 	  i = next_interval (i);
 	  if (NULL_INTERVAL_P (i))
 	    break;
 	  s = i->position;
 	}
     }
-  
+
   return result;
 }
 
@@ -1906,18 +1929,18 @@
 {
   struct gcpro gcpro1, gcpro2;
   int modified_p = 0;
-  
+
   GCPRO2 (list, object);
-  
+
   for (; CONSP (list); list = XCDR (list))
     {
       Lisp_Object item, start, end, plist, tem;
-      
+
       item = XCAR (list);
       start = make_number (XINT (XCAR (item)) + XINT (delta));
       end = make_number (XINT (XCAR (XCDR (item))) + XINT (delta));
       plist = XCAR (XCDR (XCDR (item)));
-      
+
       tem = Fadd_text_properties (start, end, plist, object);
       if (!NILP (tem))
 	modified_p = 1;
@@ -1940,7 +1963,7 @@
   for (; CONSP (list); list = XCDR (list))
     {
       Lisp_Object item, end;
-      
+
       item = XCAR (list);
       end = XCAR (XCDR (item));
 
@@ -2038,7 +2061,7 @@
 	      if (! NULL_INTERVAL_P (i))
 		{
 		  after = textget (i->plist, Qread_only);
-		  
+
 		  /* If interval I is read-only and read-only is
 		     front-sticky, inhibit insertion.
 		     Check for read-only as well as category.  */
@@ -2058,7 +2081,7 @@
 	      if (! NULL_INTERVAL_P (prev))
 		{
 		  before = textget (prev->plist, Qread_only);
-		  
+
 		  /* If interval PREV is read-only and read-only isn't
 		     rear-nonsticky, inhibit insertion.
 		     Check for read-only as well as category.  */
@@ -2078,7 +2101,7 @@
 	  else if (! NULL_INTERVAL_P (i))
 	    {
 	      after = textget (i->plist, Qread_only);
-		  
+
 	      /* If interval I is read-only and read-only is
 		 front-sticky, inhibit insertion.
 		 Check for read-only as well as category.  */
@@ -2206,7 +2229,7 @@
   interval_insert_behind_hooks = Qnil;
   interval_insert_in_front_hooks = Qnil;
 
-	       
+
   /* Common attributes one might give text */
 
   staticpro (&Qforeground);
@@ -2268,4 +2291,3 @@
 /*  defsubr (&Serase_text_properties); */
 /*  defsubr (&Scopy_text_properties); */
 }
-