Jim DeLaHunt added the comment: Marco and David, thank you again for your prompt replies.
Let me respond to both of your comments on the doctest module documentation itself. [Marco] > The example in section 26.3.3.2 [1], before the compound statement (the if/else), contains two simple statements. I also think the example is complete and straightforward for its purpose, and it does not have to be complicated adding avanced features. You are correct, it contain two simple statements. I missed this when I first read the example. Part of the problem is that the example is contrived. It is an actual test. I think it would be better to replace these two lines by a two-line test, one which sets up state and another which exercises the module under test. You believe "the example is complete and straightforward for its purpose, and it does not have to be complicated adding avanced features." I am giving you feedback that it was not complete and straightforward for me, as an ordinary software developer trying to use the documentation. [Marco] > If you want a more complex control over your tests, for instance adding fixtures, you can find how to do it later... No, control over tests is not what I am bringing up in this issue. I an concerned with documentation of doctest "Examples". [Marco] > I am -1 on this [changing 26.3.3.2]. IMHO there is no need to add extra description to a such self-explaining, clear and concise example. But this I think is also clear from the beginning. Infact, the first line of the doc says: "The doctest module searches for pieces of text that look like interactive Python sessions" [David] > As for the prompts, I agree with Marco: I don't think there is any need to add words, since it clearly says it is supposed to look like an interactive session and the reader gets reminded of the rules for that by the example provided. IMO it is not appropriate to re-document those rules here. My feedback to you is that for me, as an ordinary software developer trying to use the doctest module, this section is not "self-explaining, clear and concise", and that "How Docstring examples are recognised" is not "clear from the beginning". Perhaps we have a difference of opinion on how clear and effective this documentation is. The best way to resolve that would be to gather data: having several ordinary software developers reading the document, then measuring their comprehension. That would be hard to arrange. At least this bug report will serve as a data point. I believe that a library module documentation should at some point clearly specify how the module works. I believe section Section "26.3.3.2. How are Docstring Examples Recognized?" does poorly at that. To say, "In most cases a copy-and-paste of an interactive console session works fine, but doctest isn’t trying to do an exact emulation of any specific Python shell." is not a specification. It's a blurry generalisation. The list of "fine print" is at a better level of detail, but still doesn't mention how the parser treats statements, nor how prefixes relate to statement boundaries. I am giving you feedback that for me, as a developer trying to use the doctest module, this documentation failed to give me the comprehension I needed to be effective. [Marco] >Also this section [26.3.3.3, execution context] IMO is well written and clear. I do not know what to say... If someone else thinks it is not enough understandable, maybe the better think to do is to add a very small example, with two functions, that shows their docstrings have independent globals. [David] > It does appear that "test" is being used ambiguously in the docs. In most places it means a single statement, but in execution context it appears to be being used as a synonym for "docstring". In that section it should be replaced by "docstring". It would probably be worth checking the rest of the doc to make sure it is used consistently elsewhere as well. [David] > The execution context section makes it clear that you can use names defined earlier, as does the fact that doctests emulate interactive sessions. Both of these make it clear you can do multi line examples that use shared state. Again, I am giving you feedback that this document was not "clear" for me. I am taking the time to write this issue because I think the documentation has weaknesses, and would like to help improve it. I agree with David, that one problem in this section is that the word "test" is used with three different meanings. Some instances of the word "test" should be changed to "docstring" or similar. That would help. [David] > So in summary, I think we *need* a one word change in the execution context section, and we'll consider any other enhancements you want to propose. All right, I'll work on a patch that makes that one-word change, and offers some other concise improvements. I expect it will be more that you think necessary, given that we disagree on how "clear" the current documentation is. Given that reviews are a bottleneck, I fear my patch may grind to a halt waiting for review. But this is my first contribution to Python. We'll see. I clearly have a lot to learn. [David] > And thanks for wanting to improve the docs! You are welcome! Thank you again for your prompt responses. And thank you for all your work to build this marvelous Python language, which helps so many. [1] https://docs.python.org/3/library/doctest.html#how-are-docstring-examples-recognized ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue29428> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
