[docs] [issue29428] Doctest documentation unclear about multi-line fixtures

[R. David Murray]

R. David Murray added the comment:

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.

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.  However, if you come up with a really concise addition that clarifies it, we'll consider it.

I don't think an additional example of using previous state is required, and certainly not an additional section.  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.  However, if you come up with an example that adds value to the documentation, we'll certainly consider it.

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.

----------
nosy: +r.david.murray
versions: +Python 2.7, Python 3.5, Python 3.6

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue29428>
_______________________________________