doctest documentation suggestion
Hi doc-team, Various comments upon reading: https://docs.python.org/2/library/doctest.html In documenting doctest.IGNORE_EXCEPTION_DETAIL, you give an example that expects "ValueError: 42" (an obvious reference to HHGTTG) and points out that it'll pass (when the option is enabled) for "ValueError: 3*14", which is perfectly valid arithmetic for 42; the example would be marginally more specific if it used ValueError: 6*9, since the fact that 6*9 isn't equal to 42 (unless you use base thirteen) avoids a (very unlikely) potential confusion for the reader who might think the 3*14 only worked because 3*14 = 42. Of course, the real reason for suggesting this change is that 6*9 is what HHGTTG ends up giving us as the question whose answer is 42. Further down, in 25.2.3.6. Directives, I notice the syntax BNFL includes visible backslashes that presumably shouldn't be; directive_options ends in "\*" rather than simply "*" and the various uses of '|' are all '\|' instead. In 25.2.3.7. Warnings, where you mention I/2.**J, the mathematician in me wants you to call them "diadic rationals", but the programmer me is not persuaded it belongs in this documentation ! If the numerator's binary representation, after stripping all leading and trailing zeros, is too long then even a number of this form is not in fact safe. Under doctest.testfile, I see:
Optional argument parser specifies a DocTestParser (or subclass) that should be used to extract tests from the files. It defaults to a normal parser (i.e., DocTestParser()).
I am left unclear as to whether this argument should be the class or an instance of it. I suspect the latter, in which case the "(or subclass)" should say "(or subclass instance)"; or "a DocTestParser (or subclass)" should say "a DocTestParser (or subclass) instance". This phrasing also appears elsewhere in the page, wherever a parser argument appears. Under doctest.testmod, I see:
Also test examples reachable from dict m.__test__
with no hint that classes within m are similarly searched for __test__ dict()s, which I had understood the informal introduction to say would also be searched. That was section 25.2.3.1, which actually, just after talking about the module's .__test__, just said:
Any classes found are recursively searched similarly, to test docstrings in their contained methods and nested classes.
I guess that didn't actually say classes are searched for __test__ after all, but putting this right after the __test__ discussion - and using "similarly" - left me interpolating that. If classes within the module are not checked for a __test__ attribute, I think it would be clearer to move the "recurse into classes" paragraph from the end of 25.2.3.1 to before the .__test__ complication, which would then be clearly applicable only to the module itself (it starts "In addition..."). Back in doctest.testmod's Basic API documentation, right after talking about finding things in .__test__, it says:
Only docstrings attached to objects belonging to module m are searched.
which may mislead a reader into thinking that values of .__test__ are ignored if they don't belong to the module. I think this sentence would be better expressed (anyway) as: Only objects belonging to module m are searched for docstrings. thus making it clear that the "only" is limiting the hunt for docstrings, not limiting the entries in .__test__. I think we can take as give the search, within each docstring, for interactive examples. Eddy.
participants (1)
-
Edward Welbourne