classification
Title: Unclear language (the word ineffective) in the documentation for os.walk
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.6, Python 3.5, Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Bernt.Røskar.Brenna, docs@python, ezio.melotti, jfine2358, luiz.poleto, python-dev, r.david.murray, vstinner
Priority: normal Keywords: easy, patch

Created on 2015-10-22 17:05 by Bernt.Røskar.Brenna, last changed 2018-07-26 19:51 by jfine2358.

Files
File name Uploaded Description Edit
os_walk_docs_change_unclear_language.patch Bernt.Røskar.Brenna, 2015-10-23 09:41 Patch for os.rst review
os_walk_docs_change_unclear_language_2.patch Bernt.Røskar.Brenna, 2015-10-23 09:46 Correct patch review
os_walk_doc.patch Bernt.Røskar.Brenna, 2015-10-23 12:30 Even more correct patch review
issue25461.patch luiz.poleto, 2016-04-28 04:36 review
Messages (15)
msg253338 - (view) Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) Date: 2015-10-22 17:05
At least for me (non-english speaker), the following is confusing:

"Modifying dirnames when topdown is False is ineffective, because in bottom-up mode the directories in dirnames are generated before dirpath itself is generated."

I suggest to replace "is ineffective" with "has no effect".

Ineffective could also mean: "Has low performance", could it not?
msg253339 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-10-22 17:10
Thanks for the report.
This sounds like a reasonable request to me.
Would you like to make a patch?
(If so, you can check the devguide.)
msg253340 - (view) Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) Date: 2015-10-22 17:15
OK, I'll submit a patch
msg253342 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-10-22 17:31
As an English speaker, I prefer ineffective.  Modifying dirnames does have an effect, it modifies dirnames.  What it doesn't do (is ineffective at) is thereby altering the behavior of walk.

If you want to avoid ineffective because its meaning is subtle (a reasonable request), the correct replacement would be "modifying dirnames has no effect on the behavior of the walk", which is wordier but clearer.
msg253372 - (view) Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) Date: 2015-10-23 09:46
I agree your suggestion is better, I did not see it before submitting my first patch. I've added another patch.
msg253375 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-10-23 10:39
New changeset 0286bb18a351 by Victor Stinner in branch '3.4':
Issue #25461: Rephrase os.walk() doc
https://hg.python.org/cpython/rev/0286bb18a351

New changeset 9f68e41fb4a7 by Victor Stinner in branch '3.5':
Merge 3.4 (Issue #25461)
https://hg.python.org/cpython/rev/9f68e41fb4a7

New changeset db07937b3e49 by Victor Stinner in branch 'default':
Merge 3.4 (Issue #25461)
https://hg.python.org/cpython/rev/db07937b3e49
msg253376 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-10-23 10:42
New changeset 8247dff49113 by Victor Stinner in branch '2.7':
Issue #25461: Rephrase os.walk() doc
https://hg.python.org/cpython/rev/8247dff49113
msg253377 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2015-10-23 10:51
> If you want to avoid ineffective because its meaning is subtle (a reasonable request), the correct replacement would be "modifying dirnames has no effect on the behavior of the walk", which is wordier but clearer.

I prefer the new sentence, it's more explicit. Maybe I pushed the change too fast.

@David: are you ok with the change?
msg253379 - (view) Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) Date: 2015-10-23 12:30
Yet another patch, this time including changes to os.walk()'s docstring as well.

Ignore the two other files.
msg253380 - (view) Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) Date: 2015-10-23 13:04
A question/comment:

In this case (and there are probably other cases like it) - it seems to me that the docstring (in os.py) and the docs (in os.rst) are similar enough that the docstring from the code could be included in the docs (using Sphinx's autodoc).

What is the preferred way? Is there a reason to have it the way it is? I notice the .rst docs have some formatting applied, is it considered not OK to put formatting in docstrings?
msg253381 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2015-10-23 13:07
We don't use autodoc. It would be "nice" to have a tool to update .rst
files from .py and .c files, but it's not the case right now :-/
msg253382 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-10-23 13:10
Usually docstrings are short and to the point, and serve more as a remainder, whereas the online docs explain everything in detail.
Also rst markup in docstrings would be distractings, so we keep docstrings and online docs separated, even though there is often some overlapping.
msg253383 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2015-10-23 13:15
"Also rst markup in docstrings would be distractings, so we keep docstrings and online docs separated, even though there is often some overlapping."

Ah yes, and the doc in Doc/ directory contains more information like ".. versionchanged:: (...)", ".. versionadded:: (...)", links to other doc using reST markups, etc.

In general, the doc in Doc/ is higher quality than docstrings ;)
msg263869 - (view) Author: Luiz Poleto (luiz.poleto) * Date: 2016-04-21 02:50
The Doc/library/os.rst bit in the current patch fails to apply in all versions specified in this bug report (it seems that it was generated before the commit that included an earlier version of it).
msg264410 - (view) Author: Luiz Poleto (luiz.poleto) * Date: 2016-04-28 04:36
The change to os.rst is already committed so I modified the patch to remove it and keep only the change to os.py, which looks good and ready to be committed.
History
Date User Action Args
2018-07-26 19:51:30jfine2358setnosy: + jfine2358
2016-04-28 04:36:54luiz.poletosetfiles: + issue25461.patch

messages: + msg264410
2016-04-21 02:50:13luiz.poletosetnosy: + luiz.poleto
messages: + msg263869
2016-01-01 03:54:43ezio.melottisetstage: needs patch -> patch review
2015-10-23 13:15:30vstinnersetmessages: + msg253383
2015-10-23 13:10:57ezio.melottisetmessages: + msg253382
2015-10-23 13:07:45vstinnersetmessages: + msg253381
2015-10-23 13:04:33Bernt.Røskar.Brennasetmessages: + msg253380
2015-10-23 12:30:33Bernt.Røskar.Brennasetfiles: + os_walk_doc.patch

messages: + msg253379
2015-10-23 10:51:12vstinnersetmessages: + msg253377
2015-10-23 10:42:55python-devsetmessages: + msg253376
2015-10-23 10:39:32python-devsetnosy: + python-dev
messages: + msg253375
2015-10-23 10:15:21vstinnersetnosy: + vstinner
2015-10-23 09:46:39Bernt.Røskar.Brennasetfiles: + os_walk_docs_change_unclear_language_2.patch

messages: + msg253372
2015-10-23 09:41:47Bernt.Røskar.Brennasetfiles: + os_walk_docs_change_unclear_language.patch
keywords: + patch
2015-10-22 17:31:03r.david.murraysetnosy: + r.david.murray
messages: + msg253342
2015-10-22 17:15:39Bernt.Røskar.Brennasetmessages: + msg253340
2015-10-22 17:10:01ezio.melottisetversions: + Python 3.4, Python 3.6
nosy: + ezio.melotti

messages: + msg253339

keywords: + easy
stage: needs patch
2015-10-22 17:05:38Bernt.Røskar.Brennacreate