[docs] Different documentation for identical methods (issue 17858)

rdmurray at bitdance.com rdmurray at bitdance.com
Wed May 8 13:36:12 CEST 2013


http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst
File Doc/library/threading.rst (right):

http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#newcode373
Doc/library/threading.rst:373: reason for existence).
I don't think this parenthetical is completely accurate.  For a Lock,
even the same thread cannot acquire it (that's why RLock was later
added).  Probably just drop the parenthetical, I don't think it really
adds anything helpful.

http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#newcode375
Doc/library/threading.rst:375: If *blocking* is ``False``, the lock is
acquired only if it can be
This wording is an improvement in general, but I'm not sure a new reader
would know what "the lock is acquired only if it can be acquired" means.
 The original had "immediately without waiting" in there as well, which
while a bit redundant was also a bit more comprehensible.  Perhaps a
better wording than either would be "If *blocking* is ``False`` the call
returns immediately; the return value indicates whether or not the lock
was acquired."

Then this paragraph can be re-combined with the preceding one, since
that one describes the behavior when blocking is True.

http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#newcode379
Doc/library/threading.rst:379: specifies the maximum wait time in
seconds before returning.  A negative
I think it would be good to add "; the return value indicates whether or
not the lock was acquired." here as well.

http://bugs.python.org/review/17858/diff/8073/Doc/library/threading.rst#newcode380
Doc/library/threading.rst:380: *timeout* argument specifies an unbounded
wait.  You cannot specify
This immediately raises the question of what a 0 timeout means (and yes
I see that the original does not answer that question).  Seems like we
could have avoided having a 'blocking' keyword if we'd had timeout from
the start instead :)

So, a negative timeout is the same as not specifying a timeout and also
specifying blocking=True, and a zero timeout is the same as not
specifying a timeout and also specifying blocking=False.  We're stuck
with the API, but as long as we are perhaps we should document it that
way?

http://bugs.python.org/review/17858/


More information about the docs mailing list