[issue29371] Typo in doctest documentation
New submission from Marco Buttu:
From the doctest documentation [1]:
"Symbolic names for the flags are supplied as module constants, which can be or'ed together and passed to various functions."
Is there a typo in "...which can be or'ed together..."? Maybe "collected together"?
[1] https://docs.python.org/3/library/doctest.html#option-flags
---------- assignee: docs@python components: Documentation messages: 286254 nosy: docs@python, marco.buttu priority: normal severity: normal status: open title: Typo in doctest documentation versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Jim Fasarakis-Hilliard added the comment:
From what I understand, "or'ed" here stands for combining the options using `|` (https://docs.python.org/3/reference/expressions.html#binary-bitwise-operatio...).
You can see an example of that in the source for `doctest.py` https://hg.python.org/cpython/file/3.6/Lib/doctest.py#l144
---------- nosy: +Jim Fasarakis-Hilliard
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Marco Buttu added the comment:
I think you got the meaning. I have never read it before :/ If you think the meaning is clear enough for everyone, I close the issue.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Marco Buttu added the comment:
What about this?
"Symbolic names for the flags are supplied as module constants, which can be OR'ed together (flagA | flagB | ...) and passed to various functions."
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Jim Fasarakis-Hilliard added the comment:
I think it is fine as it is but, agree that it could be clearer. I'm simply not experienced enough to know if this change is warranted.
The docs generally do a great job in being concise (balancing brevity and completeness). A core-dev would be best to judge if brevity should be sacrificed for more complete and clear wording here.
I suggest waiting to see if any core-dev replies and, if no replies come in after a while, close it.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Changes by Raymond Hettinger raymond.hettinger@gmail.com:
---------- assignee: docs@python -> Mariatta nosy: +Mariatta, rhettinger
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Raymond Hettinger added the comment:
Mariatta, would you like to look into this and opine about whether the docs are correct as-is. If you think a change is warranted, propose a patch.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Mariatta Wijaya added the comment:
Hi everyone,
I made a patch to clarify that "or'ed" here really means "bitwise-OR'ed", and made a reference to the section of the docs about bitwise OR.
Please review and let me know if this will work.
Thanks.
---------- keywords: +patch Added file: http://bugs.python.org/file46534/issue29371.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Changes by Mariatta Wijaya mariatta.wijaya@gmail.com:
---------- stage: -> patch review
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Raymond Hettinger added the comment:
This mostly looks correct.
I would change "bitwise-OR‘ed" to "bitwise ORed". That latter form without the hyphen or apostrophe matches what is used in library/winsound.rst.
Once that change is made (in two places), go ahead an apply the patch.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Mariatta Wijaya added the comment:
Thanks, Raymond. I have an updated patch there the hypen and apostrophe are removed.
---------- versions: -Python 3.3, Python 3.4 Added file: http://bugs.python.org/file46552/issue29371v2.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Roundup Robot added the comment:
New changeset df62e833eeb1 by Mariatta Wijaya in branch '3.5': Issue #29371: Clarify bitwise OR operation in doctest option flags. https://hg.python.org/cpython/rev/df62e833eeb1
New changeset c3d779f96b20 by Mariatta Wijaya in branch '3.6': Issue #29371: merge with 3.5 https://hg.python.org/cpython/rev/c3d779f96b20
New changeset e376d2bfde9b by Mariatta Wijaya in branch 'default': Issue #29371: merge with 3.6 https://hg.python.org/cpython/rev/e376d2bfde9b
---------- nosy: +python-dev
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Roundup Robot added the comment:
New changeset 3fd198b80f29 by Mariatta Wijaya in branch '2.7': Issue #29371: Clarify bitwise OR operation in doctest option flags. https://hg.python.org/cpython/rev/3fd198b80f29
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Mariatta Wijaya added the comment:
Thanks, Marco, Jim, and Raymond :)
---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Roundup Robot added the comment:
New changeset c36939b07c1275a6c3897a917c638b0ac48885c4 by Mariatta Wijaya in branch '3.5': Issue #29371: Clarify bitwise OR operation in doctest option flags. https://github.com/python/cpython/commit/c36939b07c1275a6c3897a917c638b0ac48...
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Roundup Robot added the comment:
New changeset c36939b07c1275a6c3897a917c638b0ac48885c4 by Mariatta Wijaya in branch 'master': Issue #29371: Clarify bitwise OR operation in doctest option flags. https://github.com/python/cpython/commit/c36939b07c1275a6c3897a917c638b0ac48...
New changeset 141e1ca9844b6efe71dc7acbb6c011e1b3a4ea19 by Mariatta Wijaya in branch 'master': Issue #29371: merge with 3.5 https://github.com/python/cpython/commit/141e1ca9844b6efe71dc7acbb6c011e1b3a...
New changeset bcc59e6131af582620c2db32e19d0a064d891a59 by Mariatta Wijaya in branch 'master': Issue #29371: merge with 3.6 https://github.com/python/cpython/commit/bcc59e6131af582620c2db32e19d0a064d8...
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Roundup Robot added the comment:
New changeset 2b20a37791e3cc4536db1f99fc85ffb6e20134ab by Mariatta Wijaya in branch '2.7': Issue #29371: Clarify bitwise OR operation in doctest option flags. https://github.com/python/cpython/commit/2b20a37791e3cc4536db1f99fc85ffb6e20...
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
Roundup Robot added the comment:
New changeset c36939b07c1275a6c3897a917c638b0ac48885c4 by Mariatta Wijaya in branch '3.6': Issue #29371: Clarify bitwise OR operation in doctest option flags. https://github.com/python/cpython/commit/c36939b07c1275a6c3897a917c638b0ac48...
New changeset 141e1ca9844b6efe71dc7acbb6c011e1b3a4ea19 by Mariatta Wijaya in branch '3.6': Issue #29371: merge with 3.5 https://github.com/python/cpython/commit/141e1ca9844b6efe71dc7acbb6c011e1b3a...
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue29371 _______________________________________
participants (5)
-
Jim Fasarakis-Hilliard -
Marco Buttu
-
Mariatta Wijaya
-
Raymond Hettinger
-
Roundup Robot