classification
Title: Typo in doctest documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Mariatta Nosy List: Jim Fasarakis-Hilliard, Mariatta, docs@python, marco.buttu, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2017-01-25 13:36 by marco.buttu, last changed 2017-02-07 05:00 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
issue29371.patch Mariatta, 2017-02-06 04:00 review
issue29371v2.patch Mariatta, 2017-02-06 20:59 review
Messages (16)
msg286254 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-01-25 13:36
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
msg286255 - (view) Author: Jim Fasarakis-Hilliard (Jim Fasarakis-Hilliard) * Date: 2017-01-25 13:45
From what I understand, "or'ed" here stands for combining the options using `|` (https://docs.python.org/3/reference/expressions.html#binary-bitwise-operations).

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
msg286256 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-01-25 14:13
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.
msg286257 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-01-25 14:17
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."
msg286379 - (view) Author: Jim Fasarakis-Hilliard (Jim Fasarakis-Hilliard) * Date: 2017-01-27 17:34
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.
msg286387 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-01-27 22:23
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.
msg287076 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-02-06 04:00
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.
msg287095 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-02-06 07:59
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.
msg287171 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-02-06 20:59
Thanks, Raymond. I have an updated patch there the hypen and apostrophe are removed.
msg287188 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-02-07 04:19
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
msg287189 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-02-07 04:30
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
msg287190 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-02-07 04:32
Thanks, Marco, Jim, and Raymond :)
msg287192 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-02-07 05:00
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/c36939b07c1275a6c3897a917c638b0ac48885c4
msg287193 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-02-07 05:00
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/c36939b07c1275a6c3897a917c638b0ac48885c4

New changeset 141e1ca9844b6efe71dc7acbb6c011e1b3a4ea19 by Mariatta Wijaya in branch 'master':
Issue #29371: merge with 3.5
https://github.com/python/cpython/commit/141e1ca9844b6efe71dc7acbb6c011e1b3a4ea19

New changeset bcc59e6131af582620c2db32e19d0a064d891a59 by Mariatta Wijaya in branch 'master':
Issue #29371: merge with 3.6
https://github.com/python/cpython/commit/bcc59e6131af582620c2db32e19d0a064d891a59
msg287194 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-02-07 05:00
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/2b20a37791e3cc4536db1f99fc85ffb6e20134ab
msg287195 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-02-07 05:00
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/c36939b07c1275a6c3897a917c638b0ac48885c4

New changeset 141e1ca9844b6efe71dc7acbb6c011e1b3a4ea19 by Mariatta Wijaya in branch '3.6':
Issue #29371: merge with 3.5
https://github.com/python/cpython/commit/141e1ca9844b6efe71dc7acbb6c011e1b3a4ea19
History
Date User Action Args
2017-02-07 05:00:35python-devsetmessages: + msg287195
2017-02-07 05:00:31python-devsetmessages: + msg287194
2017-02-07 05:00:28python-devsetmessages: + msg287193
2017-02-07 05:00:26python-devsetmessages: + msg287192
2017-02-07 04:32:00Mariattasetstatus: open -> closed
resolution: fixed
messages: + msg287190

stage: patch review -> resolved
2017-02-07 04:30:23python-devsetmessages: + msg287189
2017-02-07 04:19:03python-devsetnosy: + python-dev
messages: + msg287188
2017-02-06 20:59:59Mariattasetfiles: + issue29371v2.patch

messages: + msg287171
versions: - Python 3.3, Python 3.4
2017-02-06 07:59:45rhettingersetmessages: + msg287095
2017-02-06 04:01:29Mariattasetstage: patch review
2017-02-06 04:00:55Mariattasetfiles: + issue29371.patch
keywords: + patch
messages: + msg287076
2017-01-27 22:23:54rhettingersetmessages: + msg286387
2017-01-27 21:25:58rhettingersetassignee: docs@python -> Mariatta

nosy: + rhettinger, Mariatta
2017-01-27 17:34:15Jim Fasarakis-Hilliardsetmessages: + msg286379
2017-01-25 14:17:36marco.buttusetmessages: + msg286257
2017-01-25 14:13:49marco.buttusetmessages: + msg286256
2017-01-25 13:45:21Jim Fasarakis-Hilliardsetnosy: + Jim Fasarakis-Hilliard
messages: + msg286255
2017-01-25 13:36:09marco.buttucreate