[docs] doctest documentation suggestion

[Edward Welbourne]

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.