Issue 1441264: set update method description is incorrect (original) (raw)

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.