Py2.3: Feedback on Sets

[Gary Feldman]

On Tue, 12 Aug 2003 06:02:17 GMT, "Raymond Hettinger"
<vze4rx4y at verizon.net> wrote:


>* Are the docs clear?  Can you suggest improvements?

I haven't used them yet, but since I'm working my way through
the docs in general, I thought I'd check them out and comment.

5.12
   If the optional iterable parameter is supplied, updates the set with  
   elements obtained from iteration.

Iteration over what?  Presumably "iterable."  However, this being
a reference manual, my expectations are a bias in favor of
being complete to the point of pedantry.  People shouldn't be
forced to derive inferences like this.  I think it should read
"...elements obtained from iterating over iterable."

Also, I'd like to see "iterable must be <some type spec>",
though this is a general flaw in the Python doc and is perhaps
biased by my C/C++ background where you'd never dream
of doing a reference manual without explicitly indicating the
types of every parameter.

5.12.1
  so none of the following are true: a<b, a==b, or a>b

A positive phrasing is always preferable to a negative one, and
it's always more helpful to say what things do return rather than
what they don't.  In this case, I'd say  "so each of the following
returns false: ...."

5.12.1
  s.remove(x)  	remove x from set s
  s.discard(x)  	removes x from set s if present

The implication being that remove does something else if
x isn't in s.  Again, my bias towards total completeness is
that it should say (presuming my intuition is correct) 
"remove x from set s; throws an exception if x is not a
member of s".  (Again, this is a more general problem than
just here, though I admit that there's an awful lot of C++ 
documentation that doesn't document the exceptions
that are thrown.)

Personally, I have hard time imagining where I'd want
that.  If I really cared, I could check beforehand, so I think
I'd just always use discard.  

Ditto for s.pop(), i.e. what does it do if s is empty?

  s.issubset(t)  	test whether every element in s is in t; 

I'd prefer "Tests whether s is a subset of t," and likewise
for issuperset.  I think it's fair that the reader is familiar
with sets, so the only real question is whether s.is...(t) means
s is t or t is s.  Or state both.  But being forced to parse a 
clumsy English phrase to figure it out isn't clear enough.

5.12.2
  engineering_management = engineers & programmers

Shouldn't this be engineers & management?  Also (and
here's my pedantry again) if you're using the plural form
for engineers and programmers, then it should be 
managers, not management.

Please don't take my pedantry as criticism.  It's more just
a data point - this is the one way experienced engineer
expects to see things.

Gary

PS I suppose I should mention my strongest pet peeve
with the Python documentation, which is the practice of
putting the member functions on a different page than
the class overview.  But that's not your issue, either.