New submission from Q <abon...@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@python components: Documentation files: threading.txt.patch keywords: patch messages: 160786 nosy: docs@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 <rep...@bugs.python.org> <http://bugs.python.org/issue14823> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
