Tutorial section 4.9.3 "Special Parameters" buries `/` and `*` symbols in text

[CloudeaSoft]

Location

https://docs.python.org/3/tutorial/controlflow.html#special-parameters

Current text

cpython/Doc/tutorial/controlflow.rst

Lines 749 to 772 in c375992

	Special parameters
	------------------
	By default, arguments may be passed to a Python function either by position
	or explicitly by keyword. For readability and performance, it makes sense to
	restrict the way arguments can be passed so that a developer need only look
	at the function definition to determine if items are passed by position, by
	position or keyword, or by keyword.
	A function definition may look like:
	.. code-block:: none
	def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
	----------- ---------- ----------
	| | |
	| Positional or keyword |
	| - Keyword only
	-- Positional only
	where ``/`` and ``*`` are optional. If used, these symbols indicate the kind of
	parameter by how the arguments may be passed to the function:
	positional-only, positional-or-keyword, and keyword-only. Keyword parameters
	are also referred to as named parameters.

Problem

This section is about / and * — two symbols that control how arguments are passed. But the paragraph never mentions them at the beginning. The reader has to:

1. Read an abstract sentence about "position or keyword"
2. Scan through a code example
3. Read further explanations

Only then do they finally see what the section is actually about. The two symbols (/ and *) are visually buried inside a longer line of code:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

The main characters should be introduced in the first sentence, not hidden in the middle of a code block.

Suggestion

Consider opening the section by explicitly naming / and * and stating what they do.

Readers (especially beginners) can immediately understand what the section covers and what the symbols look like, without having to dig through abstract text first.

[StanFromIreland]

#99521 proposes improving their documentation overall.

[CloudeaSoft]

#99521 proposes improving their documentation overall.

Thanks for reply. Since the documentation improvement seems already planned, I'll close this issue.