Tutorial: Add function annotation example to function tutorial

Doc/tutorial/controlflow.rst

 .. _tut-morecontrol:
 
 ***********************
 More Control Flow Tools
 ***********************
 
 Besides the :keyword:`while` statement just introduced, Python knows the usual
 control flow statements known from other languages, with some twists.
 
 
@@ skipping 628 matching lines @@
 .. _tut-annotations:
 
 Function Annotations
 --------------------
 
 .. sectionauthor:: Zachary Ware <zachary.ware@gmail.com>
 .. index::
    pair: function; annotations
    single: -> (return annotation assignment)
 
 :ref:`Function annotations <function>` are completely optional,

[eric.araujo, 2012/05/25 07:39:39]

The ref target looks wrong.  Maybe you want a link to the glossary entry that
will be added soon?  :term:`function annotations`

[zach.ware, 2012/05/25 19:23:23]

I had the same thought initially, but then I figured that this first paragraph
says roughly the same thing, and about all that the glossary entry mentions that
this doesn't is the PEP that spawned it.  The glossary entry also links to
:ref:`function`, so I figured I'd just cut out the middle-man.  The relevant
part really doesn't go into much more detail, though, so maybe the grammar
production list is the right thing to point to anyway?  I'm happy to change it
if we decide that way, though.

As a side-note, should an example be added to the :ref:`function` section?

-arbitrary metadata information about user-defined functions.  Python itself
-currently does not use annotations for anything, so this section is just for
-familiarity with the syntax.

[eric.araujo, 2012/05/25 07:39:39]

Wording improvement suggestion: “Python itself or the standard library don't use
function annotations in any way; this section just shows the syntax. 
Third-party projects are free to leverage function annotations for
documentation, type checking and other uses.”

[zach.ware, 2012/05/25 19:23:23]

Done, though I moved the negative and added a comma.

+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.
 
 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
 annotations are defined by a colon after the parameter name, followed by an
 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::
 
    >>> def f(ham: 42, eggs: int = 'spam') -> "Nothing to see here":
-   ...     print("Annotations:", f.__annotations__) # print the function's own annotations

[eric.araujo, 2012/05/25 07:39:39]

The comment seems to merely duplicate the code, which is clear enough in my
opinion.

[zach.ware, 2012/05/25 19:23:23]

Good point.  I think this was a holdover from a previous iteration of the patch
before I submitted it.  Removed.

+   ...     print("Annotations:", f.__annotations__)
    ...     print("Arguments:", ham, eggs)
    ...
    >>> f('wonderful')
    Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42}
    Arguments: wonderful spam
 
 
 .. _tut-codingstyle:
 
 Intermezzo: Coding Style
@@ skipping 47 matching lines @@
   slightest chance people speaking a different language will read or maintain
   the code.
 
 
 .. rubric:: Footnotes
 
 .. [#] Actually, *call by object reference* would be a better description,
    since if a mutable object is passed, the caller will see any changes the
    callee makes to it (items inserted into a list).