a splitting headache

[rurpy at yahoo.com]

On 10/22/2009 06:32 AM, David C. Ullrich wrote:
> On Wed, 21 Oct 2009 22:47:24 -0700 (PDT), Carl Banks
> <pavlovevidence at gmail.com> wrote:
>
>>On Oct 21, 12:46 pm, David C Ullrich <dullr... at sprynet.com> wrote:
>>> On Tue, 20 Oct 2009 15:22:55 -0700, Mensanator wrote:
>>> > On Oct 20, 1:51 pm, David C Ullrich <dullr... at sprynet.com> wrote:
>>> > I'm not saying either behaviour is wrong, it's just not obvious that the
>>> > one behaviour doesn't follow from the other and the documentation could
>>> > be
>>> > a little clearer on this matter. It might make a bit more sense to
>>> > actually
>>> > mention the slpit(sep) behavior that split() doesn't do.
>>>
>>> Have you _read_ the docs? They're quite clear on the difference
>>> between no sep (or sep=None) and sep=something:
>>
>>Even if the docs do describe the behavior adequately, he has a point
>>that the documents should emphasize the counterintutive split
>>personality of the method better.
>>
>>s.split() and s.split(sep) do different things,
>
> And they _state_ quite clearly that they do different things!
> I don't see what your complaint could possibly be.
>
>> and there is no string
>>sep that can make s.split(sep) behave like s.split().  That's not
>>unheard of but it does go against our typical expectations.  It would
>>have been a better library design if s.split() and s.split(sep) were
>>different methods.
>
> _That_ may be so. But claiming that there's a problem with the
> docs here seems silly, since the docs say exactly what happens.
>
>>That they are the same method isn't the end of the world but the
>>documentation really ought to emphasize its dual nature.

If saying exactly what happens was sufficient there
would be no need for docs, the code would suffice.
The purpose of docs is to *effectively* convey to
a human reader a complete and accurate description
of how the documented object works.  How effectively
it does that is a quality-of-implementation issue.

Many of us feel that the Python docs quality has a
lot of room for improvement.