doctest and exposing internals.

[Neil Cerutti]

I'm using doctest for the first time, and boy is it cool.

But I'm nervous about exposing library internals in the
docstring.

def glk_cancel_char_event(win):
    """ Cancel a pending request for character input.

    win must be a valid Glk window.

        >>> glk_cancel_char_event([])
        Glk library error: cancel_char_event: invalid id

    Here's an example of correct usuage.

        >>> main = glk_window_open(0, 0, 0, wintype_TextBuffer, 1)
        >>> glk_request_char_event(main)
        >>> glk_cancel_char_event(main)
        >>> main.char_request
        False

    For convenience, it's OK to call this function when a
    character input request is not pending, in which case it has
    no effect.

        >>> glk_cancel_char_event(main)
        >>> glk_window_close(main)
        (0, 0)

    """

    if win != glk_window.main:
        _strict_warning("cancel_char_event: invalid id")
        return
    glk_window.main.char_request = False

The example of correct usage it what's wrong with the docstring.

There's no interface for checking if an event is queued in Glk,
so I resorted to exposing the internal state main.char_request in
the doc string. What are the alternatives?

In addition, the last test in the docstring is only there to
ensure that other tests can open a window themselves (this
version of the library only allows one window to be open at a
time).

-- 
Neil Cerutti