https://docs.python.org/3/tutorial/controlflow.html
4.7.8. Function Annotations
[...] "The following example has a positional argument, a keyword argument, and the return value annotated:"

It is not a "positional argument" but an "optional argument".

[Robert]

> It is not a "positional argument" but an "optional argument".

I don't think I understand. Here the phrase "positional argument" in the docs is, I assume, referring to the parameter "ham: str" in the parameter list. So it's not optional; it's a required, positional-or-keyword parameter.

I don't know whether the text of this section should be being tightened up with respect to the distinction between (formal) parameters and actual arguments, though. There's a tradeoff between readability and accessibility on the one hand, and technical accuracy on the other.

https://docs.python.org/3/tutorial/controlflow.html#function-annotations
is the direct link.

As Mark said, 'ham' is a required positional-or-keyword argument.
'eggs' is an optional 'positional-or-keyword.  The sentence as is is wrong, even if Robert garbled the reason.  With the signature as it, the sentence should be "The following example has a required argument, an optional argument, and the return value annotated."

To make the existing sentence true, the signature could be changed to
  def f(ham: str, /, *, eggs: str) -> str:
But I think this would be wrong.  Annotation does not depend on how an argument is passed, but whether it has a default (making it optional).  In particular, it shows that when optional, the annotation goes *before* '= default', not after.  (It could have gone after: eggs = 'eggs': str.)

New changeset a53e9a7cf5912a44c5143e353912e44cfcfca7dc by Irit Katriel in branch 'master':
bpo-39231: correct tutorial annotations section (GH-25029)
https://github.com/python/cpython/commit/a53e9a7cf5912a44c5143e353912e44cfcfca7dc

New changeset 6fcebbb5a8cea25717804f5be9b6878104748ea5 by Miss Islington (bot) in branch '3.8':
bpo-39231: correct tutorial annotations section (GH-25029)
https://github.com/python/cpython/commit/6fcebbb5a8cea25717804f5be9b6878104748ea5

New changeset 7990072999b7e9b4ef6b1f6bb376d441a5a41d74 by Miss Islington (bot) in branch '3.9':
bpo-39231: correct tutorial annotations section (GH-25029)
https://github.com/python/cpython/commit/7990072999b7e9b4ef6b1f6bb376d441a5a41d74