[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