Issue 17417: Documentation Modification Suggestion: os.walk, fwalk (original) (raw)

Created on 2013-03-14 10:11 by gsingh, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Messages (4)
msg184155 - (view)	Author: Gurmeet Singh (gsingh)	Date: 2013-03-14 10:11
Source page: http://docs.python.org/3/library/os.html Entry: os.walk(...), os.fwalk() These functions seems to be a generator functions. An expert like yourself may have no trouble to make this out. But for novice (or for people out of touch) like myself would have preferred a starting line of this function as "A generator function that generates file names.... ", rather than currently "Generates file names...."
msg184269 - (view)	Author: Terry J. Reedy (terry.reedy) *	Date: 2013-03-15 22:18
Our standard is to start function doc entries with verbs. In any case, it is irrelevant whether os.walk is a generator function or iterator class. Which is to say, it is not part of the language definition that the object returned by os.walk() is specifically a generator, as opposed to an instance of some other iterator class. Indeed, other implementations might do differently and if we decided to recode os.walk in C to make it faster, it would be an iterator class and not a generator function (which are only written in Python). So 'generate' is being used in a generic sense. Ideas like this, and the one about changing 'topdown', would be better floated on python-list.
msg184336 - (view)	Author: Gurmeet Singh (gsingh)	Date: 2013-03-16 17:17
I am sorry to reopen this issue, if you do not like this comment, then I will reopen issues again. I am not saying to change the convention of the documentation - I just requested you to say "something" that would indicate that it is function that gives result in multiple calls. Mentioning the "generator" or "iterator" word would help a "novice" (but may not an expert like you) to understand that the object returned by this function needs to be called repeatedly and it does not return a collection of all results. After reading "... would be better floated on python-list", I do not know if my posting this comment would be termed as bugging?
msg184351 - (view)	Author: Terry J. Reedy (terry.reedy) *	Date: 2013-03-16 20:39
Reopening issues closed by a developer is worse than just 'bugging'. It wastes time, distracts from real problems, and if repeated can get your tracker account closed. Don't do it again. I gave you a suggestion: post on python-list where you can get responses from a variety of people. I read most of the original posts and some of the threads. When discussion indicates to me that there is a real problem, and has perhaps generated a solution, I have often either suggested that the original poster open an issue here or have done so myself.