<html>
<body>
After giving blanket approval to the docs I now add: <br><br>
I have a mission to set some new guidelines for Python documentation.
Perhaps this is a good place to start.<br>
Example - currently we have:<br><br>
<b>class </b><a name="l2h-1211"></a><tt>Set</tt>(
<font size=4>[</font>iterable<font size=4>]</font>)<br>
Constructs a new empty <tt>Set</tt> 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
<a href="http://www.python.org/doc/current/lib/immutable-transforms.html#immutable-transforms">5.12.3</a>.
<br><br>
Problems:<br>
The result of Set appears to be an empty <tt>Set</tt> object. The fact
that it might be filled is hidden in the parameter description.<br>
The parameter description itself is hidden in the paragraph, making it
harder to find, especially when the reader is in a hurry.<br><br>
Some suggested guidelines to improve readability and
understandability:<br>
1 - label each paragraph so we know what it is about<br>
2 - have a function paragraph that briefly but completely describes the
function<br>
3 - have labeled sections for things that can be so grouped (e.g.
parameters)<br>
4 - start the description of each thing in a new paragraph. <br><br>
Example:<br><br>
<b>class </b><a name="l2h-1211"></a><tt>Set</tt>(
<font size=4>[</font>iterable<font size=4>]</font>)<br>
function: Constructs a new empty <tt>Set</tt> object and
optionally fills it.<br>
parameters:<br>
iterable [optional] if supplied, updates the set with
elements obtained from <br>
iteration. All of the elements
in iterable should be immutable or be <br>
transformable to an immutable
using the protocol described in section
<a href="http://www.python.org/doc/current/lib/immutable-transforms.html#immutable-transforms">5.12.3</a>.
<br><br>
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.<br><br>
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".<br><br>
I also agree with the suggestion that operations that are synonymous be
so indicated in the table.<br>
<x-sigsep><p></x-sigsep>
Bob Gailer<br>
bgailer@alum.rpi.edu<br>
303 442 2625<br>
</body>
</html>