[docs] [issue14502] Document better what happens on releasing an unacquired lock

[Georg Brandl]

New submission from Georg Brandl <georg at python.org>:

>From docs at python.org:

"""
I recently ran into a situation where I could not be certain that a lock 
was currently in the acquired state. I checked the documentation to 
determine what would happen if I attempted to release a lock that was 
already released, and saw an ominous warning of "Do not call this method 
when the lock is unlocked."

Needing to know what would happen, I cautiously tested it out. I half 
expected my computer to explode as I released a lock for the second 
time, but was pleased to see it raise a 'thread.error' exception which 
could be caught and handled.

I generally expect the documentation to tell me what will happen if I do 
something invalid. In this case the documentation should indicate that a 
thread.error will be raised if you release an unlocked lock.
"""


I agree: if we know that a ThreadError will always be raised in this instance, we should document it as such.

----------
assignee: docs at python
components: Documentation
messages: 157544
nosy: docs at python, georg.brandl, pitrou
priority: normal
severity: normal
status: open
title: Document better what happens on releasing an unacquired lock
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue14502>
_______________________________________