bug#9825: 24.0.90; doc of `propertize' is misleading

bug#9825: 24.0.90; doc of `propertize' is misleading

[Drew Adams]

In (elisp) Changing Properties:
 
 This function returns a copy of STRING which has the text
 properties PROPERTIES.
 
The text is ambiguous and vague, but the impression from just saying
"has" is that the new string has ONLY properties PROPERTIES.  it gives
the impression that `propertize' SETS the properties of the string copy,
rather than just adding the given properties (setting any that are the
same).
 
E.g.:
 
(setq foo (propertize "abcd" 'face 'bold))
(setq foo (propertize foo    'mouse-face 'highlight)
 
foo =>
#("abcd" 0 4 (face bold mouse-face highlight))
 
and NOT #("abcd" 0 4 (mouse-face highlight)).
 
Note that the doc string is clear in this regard.  It says:
 
 Return a copy of STRING with text properties added.
                                              ^^^^^
 ... text properties to add to the result.
                        ^^^^^^^^^^^^^^^^^
 
In GNU Emacs 24.0.90.1 (i386-mingw-nt5.1.2600) of 2011-10-18 on MARVIN
 Windowing system distributor `Microsoft Corp.', version 5.1.2600
 configured using `configure --with-gcc (4.6) --no-opt --cflags
 -I"C:/Program Files (x86)/GnuWin32/include"
 -ID:/devel/emacs/libXpm-3.5.8/include -ID:/devel/emacs/libXpm-3.5.8/src
 -ID:/devel/emacs/gnutls-2.10.5-x86/include --ldflags
 -LD:/devel/emacs/gnutls-2.10.5-x86/lib'
 

bug#9825: 24.0.90; doc of `propertize' is misleading

[Drew Adams]

ping