[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

miss-islington added the comment: New changeset d94b762ce824e97c441f9231f0e69ef8f59beeab by Miss Islington (bot) in branch '3.7': closes bpo-25461: Update os.walk() docstring to match the online docs. (GH-11836)

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

miss-islington added the comment: New changeset c43f26eca35f22707a52fb8f3fbfc9340639b58d by Miss Islington (bot) in branch '3.8': closes bpo-25461: Update os.walk() docstring to match the online docs. (GH-11836)

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Benjamin Peterson added the comment: New changeset 734f1202a50641eb2c4bfbcd5b75247c1dc99a8f by Benjamin Peterson (Bernt Røskar Brenna) in branch 'master': closes bpo-25461: Update os.walk() docstring to match the online docs. (GH-11836)

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Change by miss-islington : -- pull_requests: +15490 pull_request: https://github.com/python/cpython/pull/15844 ___ Python tracker ___

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Change by miss-islington : -- pull_requests: +15489 pull_request: https://github.com/python/cpython/pull/15843 ___ Python tracker ___

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Change by Roundup Robot : -- pull_requests: +11867 ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

STINNER Victor added the comment: > What is the status on this? From this discussion, it looks like @vstinner > pushed changes to resolve this. Do we close this? If this still needs a > patch, then one of the patches can be reviewed in a PR on GitHub. It seems like os_walk_doc.patch and

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Joannah Nanjekye added the comment: What is the status on this? From this discussion, it looks like @vstinner pushed changes to resolve this. Do we close this? If this still needs a patch, then one of the patches can be reviewed in a PR on GitHub. -- nosy: +nanjekyejoannah

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Change by Jonathan Fine : -- nosy: +jfine2358 ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Luiz Poleto added the comment: 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. -- Added file: http://bugs.python.org/file42635/issue25461.patch

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Luiz Poleto added the comment: 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). -- nosy: +luiz.poleto

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Changes by Ezio Melotti : -- stage: needs patch -> patch review ___ Python tracker ___

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Changes by STINNER Victor : -- nosy: +haypo ___ Python tracker ___ ___

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Ezio Melotti added the comment: 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

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

STINNER Victor added the comment: > 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

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Roundup Robot added the comment: 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)

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Bernt Røskar Brenna added the comment: 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

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Roundup Robot added the comment: New changeset 8247dff49113 by Victor Stinner in branch '2.7': Issue #25461: Rephrase os.walk() doc https://hg.python.org/cpython/rev/8247dff49113 -- ___ Python tracker

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

STINNER Victor added the comment: 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 :-/ -- ___ Python tracker

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Bernt Røskar Brenna added the comment: Yet another patch, this time including changes to os.walk()'s docstring as well. Ignore the two other files. -- Added file: http://bugs.python.org/file40849/os_walk_doc.patch ___ Python tracker

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

STINNER Victor added the comment: "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:: (...)", "..

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Changes by Bernt Røskar Brenna : -- keywords: +patch Added file: http://bugs.python.org/file40846/os_walk_docs_change_unclear_language.patch ___ Python tracker

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Bernt Røskar Brenna added the comment: I agree your suggestion is better, I did not see it before submitting my first patch. I've added another patch. -- Added file: http://bugs.python.org/file40847/os_walk_docs_change_unclear_language_2.patch ___

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Bernt Røskar Brenna added the comment: OK, I'll submit a patch -- ___ Python tracker ___ ___ Python-bugs-list

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

R. David Murray added the comment: 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

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

New submission from Bernt Røskar Brenna: 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

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk

Ezio Melotti added the comment: 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.) -- keywords: +easy nosy: +ezio.melotti stage: -> needs patch versions: +Python 3.4, Python 3.6