Incorporate review comments from @willingc

python · cjrh · Oct 7, 2018 · Oct 14, 2018 · Oct 21, 2018 · Oct 21, 2018
commit dfede40791ad404ae7e7178771bdc515bfe334d1
@@ -9,10 +9,10 @@ and look like this:
     def f(x, y):
         print(x + y)
 
+    # Evaluate the function
     f(1, 2)
 
-The snippet also shows how the function is evaluated. Async functions are
-different in two respects:
+Async functions are different in two respects:
 
 .. code-block:: python
 
@@ -21,13 +21,17 @@ different in two respects:
     async def f(x, y):
         print(x + y)
 
+    # Execute the *async* function above
     asyncio.run(f(1, 2))
 
 The first difference is that the function declaration is spelled
 ``async def``. The second difference is that async functions cannot be
-``async def``. The second difference is that async functions cannot be
+:keyword:`async def`. The second difference is that async functions cannot be
-``async def``. The second difference is that async functions cannot be
+:keyword:`async def`. The second difference is that async functions cannot be
-executed by simply evaluating them. Here, we use the ``run()`` function
+executed by simply evaluating them. Instead, we use the ``run()`` function
-executed by simply evaluating them. Instead, we use the ``run()`` function
+executed by simply evaluating them. Instead, we use the :func:`~asyncio.run` function
-executed by simply evaluating them. Instead, we use the ``run()`` function
+executed by simply evaluating them. Instead, we use the :func:`~asyncio.run` function
 from the ``asyncio`` module.
-from the ``asyncio`` module.
+from the :mod:`asyncio` module.
-from the ``asyncio`` module.
+from the :mod:`asyncio` module.
 
+Executing Async Functions
+-------------------------
+
 The ``run`` function is only good for executing an async function
 from "synchronous" code; and this is usually only used to execute
-from "synchronous" code; and this is usually only used to execute
+from *synchronous* code; and this is usually only used to execute
-from "synchronous" code; and this is usually only used to execute
+from *synchronous* code; and this is usually only used to execute
 a "main" async function, from which others can be called in a simpler
-a "main" async function, from which others can be called in a simpler
+a *main* async function, from which others can be called in a simpler
-a "main" async function, from which others can be called in a simpler
+a *main* async function, from which others can be called in a simpler

@@ -1,7 +1,7 @@
 Asyncio Tutorial
 ================
 
-Programming with ``async def`` functions is different to normal Python
+Programming with ``async def`` functions is differs from normal Python
 functions; enough so that it is useful to explain a bit more
 about what ``asyncio`` is for, and how to use it in typical
 programs.