[Python-checkins] Improve asyncio.loop.call_soon() documentation (GH-20883)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/56d25add07093701c4827ea3a46b7025d9030f3c
commit: 56d25add07093701c4827ea3a46b7025d9030f3c
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2020-06-22T19:23:49-07:00
summary:

Improve asyncio.loop.call_soon() documentation (GH-20883)


* Add a glossary entry for the term "callback"
* Link to it in loop.call_soon() and in the "Concurrency and Multithreading" section

Co-authored-by: Kyle Stanley <aeros167 at gmail.com>
(cherry picked from commit a16d6970496cae5ecab5aaea2b416a4b77527cc2)

Co-authored-by: Roger Iyengar <ri at rogeriyengar.com>

files:
M Doc/glossary.rst
M Doc/library/asyncio-dev.rst
M Doc/library/asyncio-eventloop.rst

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 6189cb045049c..e997d366777b3 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -189,6 +189,10 @@ Glossary
       A list of bytecode instructions can be found in the documentation for
       :ref:`the dis module <bytecodes>`.
 
+   callback
+      A subroutine function which is passed as an argument to be executed at
+      some point in the future.
+
    class
       A template for creating user-defined objects. Class definitions
       normally contain method definitions which operate on instances of the
diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index 101e7817a95e9..0d302ea49b0de 100644
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -73,7 +73,7 @@ event loop, no other Tasks can run in the same thread.  When a Task
 executes an ``await`` expression, the running Task gets suspended, and
 the event loop executes the next Task.
 
-To schedule a callback from a different OS thread, the
+To schedule a :term:`callback` from another OS thread, the
 :meth:`loop.call_soon_threadsafe` method should be used. Example::
 
     loop.call_soon_threadsafe(callback, *args)
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 9022993e619a5..32bc219cf5c37 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -179,8 +179,8 @@ Scheduling callbacks
 
 .. method:: loop.call_soon(callback, *args, context=None)
 
-   Schedule a *callback* to be called with *args* arguments at
-   the next iteration of the event loop.
+   Schedule the *callback* :term:`callback` to be called with
+   *args* arguments at the next iteration of the event loop.
 
    Callbacks are called in the order in which they are registered.
    Each callback will be called exactly once.