[New-bugs-announce] [issue14823] Simplify threading.Lock.acquire() description
Q
report at bugs.python.org
Wed May 16 02:49:17 CEST 2012
New submission from Q <abonent at gmail.com>:
Hi there,
I suggest to improve the description of Lock.acquire()
[ http://docs.python.org/library/threading.html#threading.Lock.acquire ]
in the following way:
>>>>> current version >>>>>
Lock.acquire([blocking])
Acquire a lock, blocking or non-blocking.
When invoked without arguments, block until the lock is unlocked,
then set it to locked, and return true.
When invoked with the *blocking* argument set to true, do the same
thing as when called without arguments, and return true.
When invoked with the *blocking* argument set to false, do not
block. If a call without an argument would block, return false
immediately; otherwise, do the same thing as when called without
arguments, and return true.
<<<<< current version <<<<<
>>>>> suggested version >>>>>
Lock.acquire([blocking])
Acquire a lock, blocking or non-blocking.
When invoked with the *blocking* argument set to true
(the default), block until the lock is unlocked,
then set it to locked, and return true.
When invoked with the *blocking* argument set to false, do not
block. If a call without an argument would block, return false
immediately; otherwise, set the lock to locked, and return true.
<<<<< suggested version <<<<<
The idea is to simplify the structure of the explanation: get rid of an unnecessary "goto" -- "do the same thing as" as well as the extra branching ("when invoked without arguments" ... "when invoked with *blocking* argument set to true") .
The suggested patch for the text version of the documentation ( http://docs.python.org/download.html -> http://docs.python.org/archives/python-2.7.3-docs-text.tar.bz2 ) is attached.
PS. I did not dare to capitalize the boolean variables ("true" -> "True") to adhere to the general style of the document (obviously inherited from Java). For the same reason I didn't either change the argument signature from "[blocking]" to "[blocking=True]".
----------
assignee: docs at python
components: Documentation
files: threading.txt.patch
keywords: patch
messages: 160786
nosy: docs at python, thread13
priority: normal
severity: normal
status: open
title: Simplify threading.Lock.acquire() description
versions: Python 2.6, Python 2.7
Added file: http://bugs.python.org/file25604/threading.txt.patch
_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue14823>
_______________________________________
More information about the New-bugs-announce
mailing list