From 7e857cc34bd12265c94573d23300ea2ce86fc63c Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 22 Sep 2020 10:40:17 -0400 Subject: [PATCH 1/3] Add sentence about '/' and '*' in signatures. --- Doc/library/idle.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 43096b014fed34..979fc8fa0ca656 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -534,7 +534,9 @@ or :kbd:`)` is typed. When the cursor is in the argument part of a definition, the menu or shortcut 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 +docstring. A '/' or '*' in the signature indicates that the preceding +or following arguments are passed by position or name (keyword) only. +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. From 56398695c280d4033458836e39c97854e7d2e263 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 22 Sep 2020 11:14:03 -0400 Subject: [PATCH 2/3] bpo-35764: Rewrite the IDLE Calltips doc section --- Doc/library/idle.rst | 49 ++++++++++--------- Lib/idlelib/NEWS.txt | 2 + .../2020-09-22-11-13-45.bpo-35764.VoNa8y.rst | 1 + 3 files changed, 28 insertions(+), 24 deletions(-) create mode 100644 Misc/NEWS.d/next/IDLE/2020-09-22-11-13-45.bpo-35764.VoNa8y.rst diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 979fc8fa0ca656..8d5e5bb7a96ec1 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -527,32 +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 consists of the function signature and the first line of the -docstring. A '/' or '*' in the signature indicates that the preceding -or following arguments are passed by position or name (keyword) only. -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 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. +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 +calltip on the menu or enter its shortcut to display a calltip. + +A calltip consists of the function's signature and the docstring up to +the 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. + +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. - -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. +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 do +nothing either. 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 import statements, after +adding function definitions, or after opening an existing file. .. _code-context: diff --git a/Lib/idlelib/NEWS.txt b/Lib/idlelib/NEWS.txt index f8ec6ab5052971..7eea0a47aa6e8e 100644 --- a/Lib/idlelib/NEWS.txt +++ b/Lib/idlelib/NEWS.txt @@ -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. diff --git a/Misc/NEWS.d/next/IDLE/2020-09-22-11-13-45.bpo-35764.VoNa8y.rst b/Misc/NEWS.d/next/IDLE/2020-09-22-11-13-45.bpo-35764.VoNa8y.rst new file mode 100644 index 00000000000000..eb62d3699d5feb --- /dev/null +++ b/Misc/NEWS.d/next/IDLE/2020-09-22-11-13-45.bpo-35764.VoNa8y.rst @@ -0,0 +1 @@ +Rewrite the Calltips doc section. From a4f360f8c75b7ba1e5eefa9de396491288155a85 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 22 Sep 2020 11:32:41 -0400 Subject: [PATCH 3/3] More edits; add help.html diff. --- Doc/library/idle.rst | 14 +++++++------- Lib/idlelib/help.html | 43 +++++++++++++++++++++++-------------------- 2 files changed, 30 insertions(+), 27 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 8d5e5bb7a96ec1..a59a5d3a465703 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -531,24 +531,24 @@ 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 -calltip on the menu or enter its shortcut to display a calltip. +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's signature and the docstring up to -the first blank line or the fifth non-blank line. (Some builtin +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. -In Shell, the *accessible* functions depends on what modules have been +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 itself import turtle. The menu entry and shortcut do -nothing either. Enter ``import turtle``. Thereafter, ``turtle.write(`` +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. diff --git a/Lib/idlelib/help.html b/Lib/idlelib/help.html index b2853cffe0c26d..0edd3917e1ffa5 100644 --- a/Lib/idlelib/help.html +++ b/Lib/idlelib/help.html @@ -509,26 +509,29 @@

Automatic indentation

Calltips

-

A calltip is shown when one types ( 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 ) is typed. When the cursor is in the argument part of a definition, -the menu or shortcut 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 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.

+

A calltip is shown automatically when one types ( 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 ) 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.

+

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.

+

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.

-

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.

+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 import statements, after +adding function definitions, or after opening an existing file.

Code Context

@@ -975,7 +978,7 @@

Navigation



- Last updated on Sep 09, 2020. + Last updated on Sep 22, 2020. Found a bug?