[docs] Bug - 4.7.7

[Tim Golden]

[Keeping the conversation cc-ed to docs@ for the benefit of the other
docs admins]

On 13/04/2015 13:36, Tronster wrote:
> Hi Tim, thanks for the quick reply.
> 
> These language overview documents are great; some of the cleanest and
> clearest I've read for any language.

Thanks; nice of you to say so.


> The compiling looks like it's due to PyCharm using Python 2.6; thank you
> for mentioning this works under 3.4 ... I'll be looking into getting on
> that version (right now just using the default PyCharm install.)

Excellent.

> 
> As for making sense... I just don't understand why a string is passed to
> an integer, unless that's the point; that Python isn't strongly typed
> and that even though something is labeled an 'int' a string can be
> passed.  If that is the case; there is a lot of things happening in that
> example; perhaps break it out (e.g., single argument function, showing
> how the type is override.)

Ok; now I understand your concerns rather better. I agree that the
example is cramming rather a lot in. In particular, the unexplained
"eggs: int = 'spam'" param is highlighting the complete optionality of
the annotation. In this example, the annotation looks as if it might
well be used for some sort of parameter validation or optimisation. But
in current versions of Python, none of the built-in functionality makes
any use of it.

It would be perfectly valid to have an annotation which was a max/min
value pair, or a longer explanation of the parameter's meaning, or a
GUID which could be used to represent it to some remote system. Or anything.

Unless one of the other docs maintainers has a view, I'll dig a little
into that particular section to see who set it up in the first place
before I wade in to make changes, but I agree that it is probably too
confusing for a tutorial.

TJG

> 
> Cheers.
> 
> 
> Tronster
> http://tronster.com
> 410-299-6348