traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

bpo-35764: Rewrite the IDLE Calltips doc section (GH-22363)

This commit is contained in:
Terry Jan Reedy 2020-09-22 13:21:58 -04:00 committed by GitHub
parent 0d0e9fe2ff
commit 947adcaa13
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 48 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
Doc/library/idle.rst
View File

@ -527,30 +527,33 @@ by typing '_' after '.', either before or after the box is opened.
Calltips
^^^^^^^^
A calltip is shown when one types :kbd:`(` after the name of an *accessible*
function. A name expression may include dots and subscripts. A calltip
remains until it is clicked, the cursor is moved out of the argument area,
or :kbd:`)` is typed. When the cursor is in the argument part of a definition,
the menu or shortcut display a calltip.
A calltip is shown automatically when one types :kbd:`(` after the name
of an *accessible* function. A function name expression may include
dots and subscripts. A calltip remains until it is clicked, the cursor
is moved out of the argument area, or :kbd:`)` is typed. Whenever the
cursor is in the argument part of a definition, select Edit and "Show
Call Tip" on the menu or enter its shortcut to display a calltip.
A calltip consists of the function signature and the first line of the
docstring. For builtins without an accessible signature, the calltip
consists of all lines up the fifth line or the first blank line. These
details may change.
The calltip consists of the function's signature and docstring up to
the latter's first blank line or the fifth non-blank line. (Some builtin
functions lack an accessible signature.) A '/' or '*' in the signature
indicates that the preceding or following arguments are passed by
position or name (keyword) only. Details are subject to change.
The set of *accessible* functions depends on what modules have been imported
into the user process, including those imported by Idle itself,
and what definitions have been run, all since the last restart.
In Shell, the accessible functions depends on what modules have been
imported into the user process, including those imported by Idle itself,
and which definitions have been run, all since the last restart.
For example, restart the Shell and enter ``itertools.count(``. A calltip
appears because Idle imports itertools into the user process for its own use.
(This could change.) Enter ``turtle.write(`` and nothing appears. Idle does
not import turtle. The menu or shortcut do nothing either. Enter
``import turtle`` and then ``turtle.write(`` will work.
appears because Idle imports itertools into the user process for its own
use. (This could change.) Enter ``turtle.write(`` and nothing appears.
Idle does not itself import turtle. The menu entry and shortcut also do
nothing. Enter ``import turtle``. Thereafter, ``turtle.write(``
will display a calltip.
In an editor, import statements have no effect until one runs the file. One
might want to run a file after writing the import statements at the top,
or immediately run an existing file before editing.
In an editor, import statements have no effect until one runs the file.
One might want to run a file after writing import statements, after
adding function definitions, or after opening an existing file.
.. _code-context:

2
Lib/idlelib/NEWS.txt
View File

@ -3,6 +3,8 @@ Released on 2020-10-05?
======================================
bpo-35764: Rewrite the Calltips doc section.
bpo-40181: In calltips, stop reminding that '/' marks the end of
positional-only arguments.

43
Lib/idlelib/help.html
View File

@ -509,26 +509,29 @@ by typing ‘_’ after ‘.’, either before or after the box is opened.</p>
</div>
<div class="section" id="calltips">
<span id="id4"></span><h3>Calltips<a class="headerlink" href="#calltips" title="Permalink to this headline"></a></h3>
<p>A calltip is shown when one types <kbd class="kbd docutils literal notranslate">(</kbd> after the name of an <em>accessible</em>
function. A name expression may include dots and subscripts. A calltip
remains until it is clicked, the cursor is moved out of the argument area,
or <kbd class="kbd docutils literal notranslate">)</kbd> is typed. When the cursor is in the argument part of a definition,
the menu or shortcut display a calltip.</p>
<p>A calltip consists of the function signature and the first line of the
docstring. For builtins without an accessible signature, the calltip
consists of all lines up the fifth line or the first blank line. These
details may change.</p>
<p>The set of <em>accessible</em> functions depends on what modules have been imported
into the user process, including those imported by Idle itself,
and what definitions have been run, all since the last restart.</p>
<p>A calltip is shown automatically when one types <kbd class="kbd docutils literal notranslate">(</kbd> after the name
of an <em>accessible</em> function. A function name expression may include
dots and subscripts. A calltip remains until it is clicked, the cursor
is moved out of the argument area, or <kbd class="kbd docutils literal notranslate">)</kbd> is typed. Whenever the
cursor is in the argument part of a definition, select Edit and “Show
Call Tip” on the menu or enter its shortcut to display a calltip.</p>
<p>The calltip consists of the function’s signature and docstring up to
the latter’s first blank line or the fifth non-blank line. (Some builtin
functions lack an accessible signature.) A ‘/’ or ‘*’ in the signature
indicates that the preceding or following arguments are passed by
position or name (keyword) only. Details are subject to change.</p>
<p>In Shell, the accessible functions depends on what modules have been
imported into the user process, including those imported by Idle itself,
and which definitions have been run, all since the last restart.</p>
<p>For example, restart the Shell and enter <code class="docutils literal notranslate"><span class="pre">itertools.count(</span></code>. A calltip
appears because Idle imports itertools into the user process for its own use.
(This could change.) Enter <code class="docutils literal notranslate"><span class="pre">turtle.write(</span></code> and nothing appears. Idle does
not import turtle. The menu or shortcut do nothing either. Enter
<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">turtle</span></code> and then <code class="docutils literal notranslate"><span class="pre">turtle.write(</span></code> will work.</p>
<p>In an editor, import statements have no effect until one runs the file. One
might want to run a file after writing the import statements at the top,
or immediately run an existing file before editing.</p>
appears because Idle imports itertools into the user process for its own
use. (This could change.) Enter <code class="docutils literal notranslate"><span class="pre">turtle.write(</span></code> and nothing appears.
Idle does not itself import turtle. The menu entry and shortcut also do
nothing. Enter <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">turtle</span></code>. Thereafter, <code class="docutils literal notranslate"><span class="pre">turtle.write(</span></code>
will display a calltip.</p>
<p>In an editor, import statements have no effect until one runs the file.
One might want to run a file after writing import statements, after
adding function definitions, or after opening an existing file.</p>
</div>
<div class="section" id="code-context">
<span id="id5"></span><h3>Code Context<a class="headerlink" href="#code-context" title="Permalink to this headline"></a></h3>
@ -975,7 +978,7 @@ also used for testing.</p>
<br />
<br />
Last updated on Sep 09, 2020.
Last updated on Sep 22, 2020.
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
<br />

1
Misc/NEWS.d/next/IDLE/2020-09-22-11-13-45.bpo-35764.VoNa8y.rst Normal file
View File

@ -0,0 +1 @@
Rewrite the Calltips doc section.