[issue24028] Idle: add doc subsection on calltips

[Terry J. Reedy]

New submission from Terry J. Reedy:

The doc currently says, in the Edit menu section,

Show call tip
    After an unclosed parenthesis for a function, open a small window with function parameter hints.

I propose to add the additional information I gave in answer to https://stackoverflow.com/questions/29784273/python-idle-wont-show-docstring, in a subsubsection before or after the current one on completions https://docs.python.org/3/library/idle.html#completions  

'''
Calltips are shown when one types '(' after the name of an *acccessible* function.  The calltip should stay displayed until one types ')' or clicks the mouse or otherwise moves the cursor to dismiss it.  Cntl-\ brings it back.

A calltip consists of the function signature and the first line of the docstring.  For builtins without an accessible signature (such as, in 3.4.3, `int` or `bytes`), the calltip consists of all lines up the fifth line or the first blank line.

The set of *accessible* functions depends on what modules have been imported into the user process (where your code is executed), including those imported by Idle itself, and what code has been run (since the last restart).  For example, restart the Shell (Cntl-F6), open a new editor window, and enter

    itertools.count(

A calltip appears because Idle imports itertools into the user process for its own use.  Enter

    turtle.write(

and nothing appears, because the Idle does not import turtle.  Cntl-\ does nothing either.  Entering

    import turtle

above the function call does not immediately help, but if one runs the file to perform the import, calltips for turtle functions become available.

The suggests that one might want to run a file after writing the import statements at the top, or immediately run an existing file before editing.
'''

----------
assignee: terry.reedy
messages: 241815
nosy: terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Idle: add doc subsection on calltips
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24028>
_______________________________________