Closes #23932: Merge with 3.4

Doc/tutorial/controlflow.rst

@@ -673,11 +673,9 @@ Function Annotations
    pair: function; annotations
    single: -> (return annotation assignment)
 
-:ref:`Function annotations <function>` are completely optional,
-arbitrary metadata information about user-defined functions.  Neither Python
-itself nor the standard library use function annotations in any way; this
-section just shows the syntax. Third-party projects are free to use function
-annotations for documentation, type checking, and other uses.
+:ref:`Function annotations <function>` are completely optional metadata
+information about the types used by user-defined functions (see :pep:`484`
+for more information).
 
 Annotations are stored in the :attr:`__annotations__` attribute of the function
 as a dictionary and have no effect on any other part of the function.  Parameter
@@ -686,16 +684,17 @@ expression evaluating to the value of the annotation.  Return annotations are
 defined by a literal ``->``, followed by an expression, between the parameter
 list and the colon denoting the end of the :keyword:`def` statement.  The
 following example has a positional argument, a keyword argument, and the return
-value annotated with nonsense::
+value annotated::
 
-   >>> def f(ham: 42, eggs: int = 'spam') -> "Nothing to see here":
+   >>> def f(ham: str, eggs: str = 'eggs') -> str:
    ...     print("Annotations:", f.__annotations__)
    ...     print("Arguments:", ham, eggs)
+   ...     return ham + ' and ' + eggs
    ...
-   >>> f('wonderful')
-   Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42}
-   Arguments: wonderful spam
-
+   >>> f('spam')
+   Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}
+   Arguments: spam eggs
+   'spam and eggs'
 
 .. _tut-codingstyle: