[Python-Dev] Warnings

Cameron Simpson cs at zip.com.au
Wed Dec 7 02:23:12 CET 2011

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_!

Cameron Simpson <cs at zip.com.au> DoD#743

There is one evil which...should never be passed over in silence but be
continually publicly attacked, and that is corruption of the language...
        - W.H. Auden

More information about the Python-Dev mailing list