Steven D'Aprano <steve+pyt...@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. 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.) ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue36675> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
