[docs] [issue36675] Doctest directives and comments missing from code samples
report at bugs.python.org
Thu May 16 13:38:34 EDT 2019
Steven D'Aprano <steve+python at pearwood.info> added the comment:
> Doctest directives in code examples should be suppressed everywhere
> *except* in the doctest.html examples showing how to use directives.
> The patch only exposes them for doctest.html and not for ctypes or
> anywhere else.
Thanks for the patch, and the extra information, but I disagree with the
decision to suppress the directives.
The reason I found this problem in the first case was that I started
with the ctypes documentation, where it says:
"Since some code samples behave differently under Linux, Windows, or Mac
OS X, they contain doctest directives in comments."
and I was very keen to see those directives so I could learn the right
way to deal with platform-dependent doctests. I was very confused that
they weren't visible.
I think that doctest directives are as much a part of documenting
correct usage as any other part of the example code, and they are
(semi-)human readable and (almost) self-documenting.
Consider this example from ctypes:
>>> c_wchar_p("Hello, World")
In the absence of a directive, but knowing that it may have been
surpressed, I don't know how to interpret that. Is the output some
arbitrarily chosen value that doctest ought to skip? Or is that the
actual output that c_wchar_p("Hello, World") will return every single
time without fail?
If I was a ctypes expert, it might be blindingly obvious to me, but I'm
not, so I'm left in the dark. I don't know whether I should expect that
precise output each and every time, or something platform and
If the directive #doctest:+SKIP was visible, I would know that it was an
arbitrarily chosen example.
My preference would be:
- keep the doctest directives visible, everywhere;
- make them a clickable link to the appropriate section
in the doctest documentation;
- and, if possible, on mouse-over, they should display a
tooltip with a message like
"The output of this example is arbitrary."
Or similar wording.
> They really should not be in the dir example code that I linked to.
On the contrary: I think that the presence of the +SKIP directive helps
demonstrate that the output shown is a made-up example, not normative.
(Of course it helps that I know doctest, but even if I didn't, the
tooltip message would help.)
Python tracker <report at bugs.python.org>
More information about the docs