Py2.3: Feedback on Sets

[Bob Gailer]

After giving blanket approval to the docs I now add:

I have a mission to set some new guidelines for Python documentation. 
Perhaps this is a good place to start.
Example - currently we have:

class Set( [iterable])
Constructs a new empty Set object. If the optional iterable parameter is 
supplied, updates the set with elements obtained from iteration. All of the 
elements in iterable should be immutable or be transformable to an 
immutable using the protocol described in section 
<http://www.python.org/doc/current/lib/immutable-transforms.html#immutable-transforms>5.12.3. 


Problems:
The result of Set appears to be an empty Set object. The fact that it might 
be filled is hidden in the parameter description.
The parameter description itself is hidden in the paragraph, making it 
harder to find, especially when the reader is in a hurry.

Some suggested guidelines to improve readability and understandability:
1 - label each paragraph so we know what it is about
2 - have a function paragraph that briefly but completely describes the 
function
3 - have labeled sections for things that can be so grouped (e.g. parameters)
4 - start the description of each thing in a new paragraph.

Example:

class Set( [iterable])
   function: Constructs a new empty Set object and optionally fills it.
   parameters:
     iterable [optional] if supplied, updates the set with elements 
obtained from
         iteration. All of the elements in iterable should be immutable or be
         transformable to an immutable using the protocol described in 
section 
<http://www.python.org/doc/current/lib/immutable-transforms.html#immutable-transforms>5.12.3. 


What do you think? If this layout is appealing, let's use the set docs as a 
starting point to model this approach. I for one am willing to apply this 
model to the rest ot the set docs, and help update other docs, but not all 
of them.

BTW I also have a problem with the term "Common uses". "Common" suggests 
that these are better, or more frequent. I suggest "Some examples of 
application of sets".

I also agree with the suggestion that operations that are synonymous be so 
indicated in the table.

Bob Gailer
bgailer at alum.rpi.edu
303 442 2625

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20030814/0a86afab/attachment.html>
-------------- next part --------------

---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.506 / Virus Database: 303 - Release Date: 8/1/2003