> 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.

https://docs.python.org/3/library/ctypes.html

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")
    c_wchar_p(140018365411392)

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 
implementation specific.

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.
> https://docs.python.org/3/library/functions.html#dir

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.)