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 616 matching lines @@
    ...     """Do nothing, but document it.
    ...
    ...     No, really, it doesn't do anything.
    ...     """
    ...     pass
    ...
    >>> print(my_function.__doc__)
    Do nothing, but document it.
 
        No, really, it doesn't do anything.
+
+
+.. _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.

+
+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("Arguments:", ham, eggs)
+   ...
+   >>> f('wonderful')
+   Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42}
+   Arguments: wonderful spam
 
 
 .. _tut-codingstyle:
 
 Intermezzo: Coding Style
 ========================
 
 .. sectionauthor:: Georg Brandl <georg@python.org>
 .. index:: pair: coding; style
 
@@ skipping 42 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).