Typo in doctest documentation

[marco-buttu]

BPO	29371
Nosy	@rhettinger, @marco-buttu, @DimitrisJim, @Mariatta
Files	issue29371.patch issue29371v2.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/Mariatta'
closed_at = <Date 2017-02-07.04:32:00.447>
created_at = <Date 2017-01-25.13:36:09.620>
labels = ['3.7', 'docs']
title = 'Typo in doctest documentation'
updated_at = <Date 2017-02-07.05:00:35.215>
user = 'https://github.com/marco-buttu'

bugs.python.org fields:

activity = <Date 2017-02-07.05:00:35.215>
actor = 'python-dev'
assignee = 'Mariatta'
closed = True
closed_date = <Date 2017-02-07.04:32:00.447>
closer = 'Mariatta'
components = ['Documentation']
creation = <Date 2017-01-25.13:36:09.620>
creator = 'marco.buttu'
dependencies = []
files = ['46534', '46552']
hgrepos = []
issue_num = 29371
keywords = ['patch']
message_count = 16.0
messages = ['286254', '286255', '286256', '286257', '286379', '286387', '287076', '287095', '287171', '287188', '287189', '287190', '287192', '287193', '287194', '287195']
nosy_count = 6.0
nosy_names = ['rhettinger', 'docs@python', 'python-dev', 'marco.buttu', 'Jim Fasarakis-Hilliard', 'Mariatta']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue29371'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7']

[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

[DimitrisJim]

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

[marco-buttu]

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.

[marco-buttu]

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."

[DimitrisJim]

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.

[rhettinger]

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.

[Mariatta]

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.

[rhettinger]

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.

[Mariatta]

Thanks, Raymond. I have an updated patch there the hypen and apostrophe are removed.

[python-dev]

New changeset df62e833eeb1 by Mariatta Wijaya in branch '3.5':
Issue bpo-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 bpo-29371: merge with 3.5
https://hg.python.org/cpython/rev/c3d779f96b20

New changeset e376d2bfde9b by Mariatta Wijaya in branch 'default':
Issue bpo-29371: merge with 3.6
https://hg.python.org/cpython/rev/e376d2bfde9b

[python-dev]

New changeset 3fd198b80f29 by Mariatta Wijaya in branch '2.7':
Issue bpo-29371: Clarify bitwise OR operation in doctest option flags.
https://hg.python.org/cpython/rev/3fd198b80f29

[Mariatta]

Thanks, Marco, Jim, and Raymond :)

[python-dev]

New changeset c36939b07c1275a6c3897a917c638b0ac48885c4 by Mariatta Wijaya in branch '3.5':
Issue bpo-29371: Clarify bitwise OR operation in doctest option flags.
c36939b

[python-dev]

New changeset c36939b07c1275a6c3897a917c638b0ac48885c4 by Mariatta Wijaya in branch 'master':
Issue bpo-29371: Clarify bitwise OR operation in doctest option flags.
c36939b

New changeset 141e1ca9844b6efe71dc7acbb6c011e1b3a4ea19 by Mariatta Wijaya in branch 'master':
Issue bpo-29371: merge with 3.5
141e1ca

New changeset bcc59e6131af582620c2db32e19d0a064d891a59 by Mariatta Wijaya in branch 'master':
Issue bpo-29371: merge with 3.6
bcc59e6

[python-dev]

New changeset 2b20a37791e3cc4536db1f99fc85ffb6e20134ab by Mariatta Wijaya in branch '2.7':
Issue bpo-29371: Clarify bitwise OR operation in doctest option flags.
2b20a37

[python-dev]

New changeset c36939b07c1275a6c3897a917c638b0ac48885c4 by Mariatta Wijaya in branch '3.6':
Issue bpo-29371: Clarify bitwise OR operation in doctest option flags.
c36939b

New changeset 141e1ca9844b6efe71dc7acbb6c011e1b3a4ea19 by Mariatta Wijaya in branch '3.6':
Issue bpo-29371: merge with 3.5
141e1ca