Reorganize the spec

[JelleZijlstra]

According to Eric's suggested outline in https://discuss.python.org/t/proposed-initial-typing-spec/39389/6?u=jelle

[Daverball]

While this isn't really the point of this PR, it just so happens that it covers the entire text of the spec, so it's easy to make suggestions for some of the low hanging fruits in the examples.

[Daverball]

Suggested change

	foo(x_y, y_x) # Could return (__a: int, __b: str) -> bool
	foo(x_y, y_x) # Could return (__a: int, __b: str, /) -> bool

Just to really drive home the fact that these are positional only arguments

[JelleZijlstra]

We shouldn't use the double underscore convention at all though.

[Daverball]

Usually I'd agree and my first instinct was to change it to (a: int, b: str, /), however we aren't really defining a function here, we just want to communicate that the signature of the combined ParamSpec should be positional only, so using double underscores in this case I think helps communicate that the name doesn't really matter a bit better. I was also considering (int, str) -> bool, because I think that's how mypy would display that signature, but that only works because mypy uses the qualified names for the types to disambiguate them from parameter names.

Ideally we would have a common way to describe signatures that we can also use in Callable or other generics with ParamSpec where the positional only arguments don't have a name at all, the mixed ones might and keyword only arguments do.

[JelleZijlstra]

I feel we shouldn't use the double underscore convention for pos-only parameters in the spec at all: it's a historical hack that has become obsolete now that Python 3.7 is dead. Typeshed will soon stop using it. Users shouldn't need to see it anywhere.

You make good points though; I need to look at this example more closely to decide what I'd want here.

[Daverball]

Yeah, another thing I considered was (_: int, _: str, /) -> bool, although that would be invalid syntax once you would try it in a def.

[JelleZijlstra]

I'm going to change this in a separate PR.

[JelleZijlstra]

#17