[Python-Dev] Warnings

[Ethan Furman]

Georg Brandl wrote:
> Am 07.12.2011 02:23, schrieb Cameron Simpson:
>> On 30Nov2011 22:10, Raymond Hettinger <raymond.hettinger at gmail.com> wrote:
>> | When updating the documentation, please don't go overboard with warnings.
>> | The docs need to be worded affirmatively -- say what a tool does and show how to use it correctly.
>> | See http://docs.python.org/documenting/style.html#affirmative-tone
>>
>> I come to this late, but if we're going after the docs...
>>
>> At the above link one finds this text:
>>
>>   This assures that files are flushed [...]
>>
>> It does not. It _ensures_ that files are flushed. The doco style "affirmative
>> tone" _assures_. The coding practice _ensures_!
>>
>> Pedanticly,
> 
> Oh, come on, surely this doesn't effect the casual reader?

No, of course not -- although it might /affect/ said reader by causing 
him/her to think, "I don't think that word means what you think it 
means..."  ;)

Seriously, it's best to use the correct words with the correct meanings. 
  If someone is willing to fix it, let them.

~Ethan~