classification
Title: Different documentation for identical methods
Type: enhancement Stage:
Components: Documentation Versions: Python 3.4
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: amysyk, docs@python, georg.brandl, r.david.murray
Priority: normal Keywords: patch

Created on 2013-04-27 22:58 by amysyk, last changed 2013-05-09 15:19 by amysyk.

Files
File name Uploaded Description Edit
issue17858.patch amysyk, 2013-04-27 23:02 patch for issue 17858 review
issue17858.patch amysyk, 2013-04-28 17:02 Issue 17858 Patch 2 review
issue17858.patch amysyk, 2013-05-05 17:10 Issue 17858 Patch 3 review
issue17858.patch amysyk, 2013-05-09 15:19 issue 17858 Patch 4
Messages (9)
msg187945 - (view) Author: Andriy Mysyk (amysyk) * Date: 2013-04-27 22:58
Use _thread.Lock.acquire() documentation for threading.Lock.acquire().

threading.Lock inherits acquire() method from _thread.Lock.  The two acquire() methods are identical in their functionality yet have different documentation. Documentation for threading.Lock.acquire() creates the impression that the function is more complex or harder to use than it actually is. See http://docs.python.org/devguide/documenting.html#economy-of-expression for guidelines.
msg187946 - (view) Author: Andriy Mysyk (amysyk) * Date: 2013-04-27 23:02
I am attaching a patch that applies _thread.Lock.acquire() documentation to the functionally identical threading.Lock.acquire().
msg187947 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-04-27 23:35
For the record, both the _thread docs and the threading docs for acquire were updated in 01d1fd775d16 as part of issue 7316.  Some at least of the differences come from 6ab4128acccc (issue 14823).  That makes it likely that the threading docs are the better of the two.
msg187948 - (view) Author: Andriy Mysyk (amysyk) * Date: 2013-04-27 23:51
Issue 14823 indeed improved threading documentation. However, even with the improvement threading documentation makes acquire() appear to be more complex and harder to use than it actually is.
msg187965 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-04-28 06:02
This patch includes changes from #17851, please remove that (but you can remove the comma after "block").
msg188004 - (view) Author: Andriy Mysyk (amysyk) * Date: 2013-04-28 17:02
Apologies.  I did not mean to include 17851 changes. Removed the changes, leaving out the comma after "block" in the attached patch.
msg188450 - (view) Author: Andriy Mysyk (amysyk) * Date: 2013-05-05 17:10
Made changes suggested by Ezio Melotti in the attached patch.
msg188717 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-05-08 11:39
Added review comments with suggestions on improving the wording further.  Once we agree on wording we could apply this to the _thread docs as well, I suppose.

Ah, I see that one of the changes I found problematic was suggested by Ezio :)
msg188781 - (view) Author: Andriy Mysyk (amysyk) * Date: 2013-05-09 15:19
Incorporated R. David Murray's feedback...

   .. method:: acquire(blocking=True, timeout=-1)

      Without any optional argument, this method acquires the lock
      unconditionally, if necessary waiting until it is released by another
      thread (only one thread at a time can acquire a lock).

      If *blocking* is ``False``, the call returns immediately.  If *blocking*
      is ``True``, the lock is acquired unconditionally. In both cases
      the return value indicates whether or not the lock was acquired.

      If the floating-point *timeout* argument is present and positive, it
      specifies the maximum wait time in seconds before returning; the return
      value indicates whether or not the lock was acquired.  A negative
      *timeout* argument specifies an unbounded wait and is the same as not
      specifying a *timeout* and also setting *blocking* to ``True``.  A zero
      *timeout* is the same as not specifying a *timeout* and setting *blocking*
      to ``False``.  You cannot specify a *timeout* if *blocking* is ``False``.

      The return value is ``True`` if the lock is acquired successfully,
      ``False`` if not.
History
Date User Action Args
2013-05-09 15:19:20amysyksetfiles: + issue17858.patch

messages: + msg188781
2013-05-08 11:39:04r.david.murraysetmessages: + msg188717
2013-05-05 17:10:04amysyksetfiles: + issue17858.patch

messages: + msg188450
2013-04-28 17:02:28amysyksetfiles: + issue17858.patch

messages: + msg188004
2013-04-28 06:02:19georg.brandlsetnosy: + georg.brandl
messages: + msg187965
2013-04-27 23:51:44amysyksetmessages: + msg187948
2013-04-27 23:35:23r.david.murraysetnosy: + r.david.murray
messages: + msg187947
2013-04-27 23:02:31amysyksetfiles: + issue17858.patch
keywords: + patch
messages: + msg187946
2013-04-27 22:58:05amysykcreate