[ python-Bugs-1441264 ] set update method description is incorrect

[SourceForge.net]

Bugs item #1441264, was opened at 2006-03-01 15:19
Message generated for change (Settings changed) made by tjreedy
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1441264&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.4
>Status: Closed
>Resolution: Invalid
Priority: 5
Submitted By: Richard King (rickbking)
Assigned to: Nobody/Anonymous (nobody)
Summary: set update method description is incorrect

Initial Comment:
Update is described as returning the set with the new 
members, but it only updates the set and returns None.

----------------------------------------------------------------------

>Comment By: Terry J. Reedy (tjreedy)
Date: 2006-03-05 23:40

Message:
Logged In: YES 
user_id=593130

You are right.

It is standard in Python for mutating methods to return 
None.  

The doc strings for update are more or less OK.
>>> set.update.__doc__
'Update a set with the union of itself and another.'
>>> sets.Set.update.__doc__
'Add all values from an iterable (such as a list or file).'

But
http://docs.python.org/lib/types-set.html 
http://docs.python.org/lib/set-objects.html
both incorrectly describes the first four update methods 
as returning the set after the update

(In the furture, giving specific section references or url 
for questionable docs would help verify the report.)

Verifying the expected behavior for the module:
>>> from sets import Set as S
>>> c=S([1,2,3])
>>> d=S([2,3,4])
>>> c.update(d)
>>> c
Set([1, 2, 3, 4])
# etc

Suggested fixes for both files:  In "The following table 
lists operations available ..." add 'mutation' 
before 'operatons' and follow the sentence with "All 
return None."
Change "return set s with elements added from t"
to "add elements from t to s"
Change "return set s keeping only elements also found in t"
to "remove elements of s not found in t"
Change "return set s after removing elements found in t"
to "remove elements of s also found in t"
Change "return set s after removing elements found in t"
to "remove elements of s also in t and add elements of t 
not in s"

Verify with set/sets author (RH I believe).

Additional glitch: at the bottom of 
http://docs.python.org/lib/types-set.html
there is a link to 'sets'
http://docs.python.org/lib/module-comparison-to-builtin-
set.html
I currently get 'page not found' message.

While on the topic of doc glitches:
http://docs.python.org/lib/typesmapping.html
has title "2.3.8 Mapping Types -- classdict"
'classdict'? looks like a typo.


----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1441264&group_id=5470