New submission from Kyle Stanley <aeros...@gmail.com>:
Currently in the documentation for print() (https://docs.python.org/3/library/functions.html#print), the phrasing for the flush argument is: Whether output is buffered is usually determined by file, but if the flush keyword argument is true, the stream is forcibly flushed. For the sake of clarity, I would recommend changing it to one of the following: 1) Whether or not output is buffered is usually determined by *file*, but if the *flush* keyword argument is true, the stream is forcibly flushed. 2) Whether or not output is buffered is usually determined by *file*. However, if the *flush* keyword argument is true, the stream is forcibly flushed. 3) Output buffering is usually determined by *file*. However, if the *flush* keyword argument is true, the stream is forcibly flushed. 4) Output buffering is usually determined by *file*. However, if *flush* is true, the stream is forcibly flushed. Each of the options are ordered in difference from the original, with one being the closest. The first couple options simply attempt improve the readability without changing the message itself significantly. In the third option, "output is buffered" is replaced by "output buffering", which is a commonly used programming term for what is being described. The fourth option removes "keyword argument" after *flush*, since it was not mentioned for *file* (which is also a keyword argument). Users can simply look at the function arguments to see that it's a keyword argument. Explicitly specifying this seems like it might be in partial violation of https://devguide.python.org/documenting/#economy-of-expression and https://devguide.python.org/documenting/#audience. I'll be submitting a PR to attach to this issue soon. Let me know if this change is helpful, and if so, which option (or variation) provides the most concise and helpful explanation to users. ---------- messages: 347778 nosy: aeros167, eric.araujo, ezio.melotti, mdk, willingc priority: normal severity: normal status: open title: Docs: Improve phrasing of flush argument for print() _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue37581> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
